logo
搜索
我的图书馆

发文章

发文工具

其他工具

留言交流
搜索
分享

2、Django开发总结：项目开发推荐编码规范（官方）

 汉无为 2023-08-03 发布于湖北

图片

设计规范

编码规范

  • CSS3编码规范

  • H5编码规范

  • Nodejs(JavaScript)编码规范

  • Vue编码规范

  • Python3编码规范

  • Django编码规范

  • C语言编码规范

  • C++编码规范

  • Go编码规范

  • Verilog编码规范

  • PHP编码规范

  • Java编码规范

安全指南

  • 浏览器（Web开发）安全指南

  • Nodejs(JavaScript)安全指南

  • C/C++安全指南

  • Go安全指南

  • PHP安全指南

  • Java安全指南

  • 数据库(MySQL、MongoDB、PGSQL、Redis、ElasticSearch等)安全指南

  • Windows安全配置指南

  • Linux安全配置指南

Django是一个流行的Python Web框架，为了保证代码的可读性和可维护性，Django官方提供了一套编码规范。本文将详细介绍Django官方推荐的编码规范。每种编程语言或框架都有自己的编码规范, 基于Python语言的Django框架也不例外。代码规范提供的指导方针旨在提高代码的可读性，并使其在各种Python代码中保持一致。

更多技术点和问题欢迎后台留言讨论，敬请关注公众号CTO Plus后续发文。

Python编码规范

Django是Python语言写成的框架，所以其代码也要求符合Python的PEP8编码规范，PEP 8只是个指南，并非强制约束。可以使用Pylint、Flake8等工具来辅助检测Python代码是否规范，以及使用autopep8、isort等工具来自动编排代码规范，使用pip安装即可。这部分的内容将在后面详细做介绍，请关注公众号：CTO Plus后续的发文。

PyCharm已自带代码检查工具，使用时还推荐使用.editorconfig文件来配置编码规范，比如html中使用2个空格做缩进。

基本规范 

1. 模块名：使用小写字母，单词之间使用下划线分隔。

2. 类名：使用驼峰式命名法，首字母大写（ShowCase）的方式命名（或能够返回类的工厂函数）。

3. 函数和方法名：使用小写字母，单词之间使用下划线分隔。

4. 变量名：使用小写字母，单词之间使用下划线分隔。

5. 常量名：使用大写字母，单词之间使用下划线分隔。

6. 缩进：使用4个空格进行缩进。

7. 系统性移除代码里多余的空格。

8. PEP8规范里每行代码字符数要求不超过79个，而Django允许每行最多119个字符, 这是GitHub代码审查时可以接受的每行代码的最大长度。

9. 如果有一行代码非常长，建议使用如下方式换行。括号单独成行，依然使用4个空格为每行内容做缩进：

raise AttributeError(

'Here is a multiline error message '

'shortened for clarity.'

)

而不是采用如下垂直对齐的方式（这是很多新手易范的错误):

raise AttributeError('Here is a multiline error message '

'shortened for clarity.')

第一种方式更好的原因是，当需要改变某行文字内容时，不需要再进行手动对齐了。

10. 字符串的引号使用

Django对字符串推荐使用单引号，只有当字符串本身里包含单引号时才使用双引号。对于三引号docstring注释，Django推荐3个双引号，如下所示：

def test_foo():

'''

A test docstring looks like this (#123456).

'''

pass

11. 空格：在二元运算符两侧使用一个空格，函数参数列表中逗号后面使用一个空格。

12. 注释：使用英文，避免使用缩写和简写，注释应该清晰明了，不应该出现拼写错误。

导包(import)

1. 包的导入规范

导入：每个导入应该独占一行，应该按照标准库、第三方库、自己编写的模块的顺序进行导入。

导包时要注意区分哪些是来未来的，哪些是python的标准库，哪些是第三方包，哪些是Django自带的标准包以及开发者自己编写的包。对于Django自带的包使用绝对路径，对于开发者自己编写的包, 使用相对路径。

另外还需要注意最后一行导包(import)与自己代码之间的空格距离，与一般模块代码空格一行即可，但与的第一个函数或类必需空格两行。

2. 没有用到的包或import需要移除。

示范代码如下所示：

# futurefrom __future__ import unicode_literals# standard libraryimport jsonfrom itertools import chain# third-partyimport bcrypt# Djangofrom django.http import Http404from django.http.response import (Http404, HttpResponse, HttpResponseNotAllowed, StreamingHttpResponse, cookie,)# local Djangofrom .models import LogEntry# try/excepttry: import yamlexcept ImportError: yaml = NoneCONSTANT = 'foo'
class Example:    # ...

还可以使用isort帮实现自动化导包顺序，使用如下命令即可：

python -m pip install isort

isort -rc .

关于isort工具的集成和使用请参考公众号：CTO Plus另外一篇文章《代码规范扫描与自动化编排工具：isort》。

模板（Templates）

Django官方推荐的模板编码规范包括以下几点：

1. 模板中应该尽量避免使用Python代码，只使用最基本的控制语句和变量。

2. 模板中应该使用缩进和换行符使代码更易读。

3. 模板中应该使用模板继承和模板包含来避免重复代码。

4. 对于模板中的变量，遵循大括号及标签内容之间使用一个（只需一个）空格

# Good

{{ foo }}

# Bad

{{foo}}

5. 模板应该使用Django模板语言（DTL）编写，以便使用模板标签和过滤器等功能。

6.模板名称应该使用snake_case命名规范。

7.模板应该完整地表示一个页面或一个页面组件。

8.模板应该避免使用过多的控制流和逻辑。

视图（Views）

Django官方推荐的视图编码规范包括以下几点：

1. 每个视图函数只处理一个HTTP方法，例如GET或POST。

2. 视图函数应该返回HttpResponse或JsonResponse对象。

3. 推荐使用类视图代替函数视图，类视图可以提高代码的可重用性和可维护性。

4. 类视图应该继承自django.views.generic.View类或其子类。

5. 类视图的名称应该描述其功能或模型，例如CreateView、ListView。

6. 类视图应该实现get、post、put、delete等HTTP方法。

7. 对于函数视图，第一个参数永远是request,不要擅自修改, 应该被命名为 request。

# Rightdef my_view(request, foo):# ...
# Wrongdef my_view(req, foo):    # ...

模型（Models）

Django官方推荐的模型编码规范包括以下几点：

1. 模型名称应该使用TitleCase（首字母大写的驼峰式）或camelCase（除首字母外其他字母大写的驼峰式）命名规范。

2. 每个模型应该定义在一个单独的模块中，且应该保证模型的可重用性。

3. 模型的属性名称应该使用snake_case（蛇形命名）命名规范，例如created_at、updated_at等。

4. 模型应该定义__str__方法，以便在管理页面中显示有意义的名称。

5. 每个模型应该定义Meta类，以便自定义模型的表名、排序顺序等属性。

6. 模型的外键关系应该使用ForeignKey、OneToOneField或ManyToManyField，而不是使用CharField或IntegerField等类型来表示。

7. 模型的字段应该是小写字母，可以使用下划线连接，不要使用驼峰命名。

# Goodclass Person(models.Model): first_name = models.CharField(max_length=20) last_name = models.CharField(max_length=40)
# Badclass Person(models.Model): FirstName = models.CharField(max_length=20)   Last_Name = models.CharField(max_length=40)

8. 模型的Meta选项应该在自定义模型字段最后，且与最后一条字段间有一空行。

class Person(models.Model):  first_name = models.CharField(max_length=20)      last_name = models.CharField(max_length=40)    class Meta:  verbose_name_plural = 'people'

9. model内的类和方法的定义顺序应该遵循如下顺序

有时需要给模型定义__str__方法，重写save方法或自定义其它方法，这些方法应该放在Meta选项后面，且遵循下面的顺序（不是所有项都是必需的）：

  • 定义的模型字段

  • 定制的Manager（管理器属性）方法

  • class Meta选项

  • def __unicode__()

  • def __str__()

  • def save()

  • def get_absolute_url()

  • 其它自定义方法

如果一个 model 字段定义了 choices，那么定义的多元元组的名称应该全部大写。

class MyModel(models.Model): DIRECTION_UP = 'U' DIRECTION_DOWN = 'D' DIRECTION_CHOICES = ( (DIRECTION_UP, 'Up'), (DIRECTION_DOWN, 'Down'), )

django.conf.settings的规范

Django官方推荐的django.conf.settings编码规范包括以下几点：

1. 模块不常用的设置项被储存在 django.conf.settings中

2. 模块通常不应使用存储在django.conf.settings中的顶级设置（即在导入模块时进行评估）。

3. settings应该使用全局配置的方式，以便在整个应用程序中共享配置参数。

4. 应该避免在配置文件中硬编码敏感信息，例如用户名、密码等。

5. Django的默认配置参数应该在写入配置文件前进行覆盖或修改，以满足应用程序的需求。

6. 允许手动配置设置（即不依赖于DJANGO_SETTINGS_MODULE环境变量），并且可能如下：

from django.conf import settings

settings.configure({}, SOME_SETTING='foo')

但是，如果在settings.configure行之前访问了任何设置，则此操作将不起作用。（在内部，设置是一个LazyObject，如果尚未配置，则在访问设置时会自动配置它自己）。

因此，如果有一个模块包含如下代码：

from django.conf import settings

from django.core.urlresolvers import get_callable

default_foo_view = get_callable(settings.FOO_VIEW)

…

然后导入此模块将导致配置设置对象。这意味着，第三方在顶级导入模块的能力与手动配置设置对象的能力不兼容，或者在某些情况下非常困难。

必须使用一定程度的惰性或间接性来代替上面的代码，例如django.utils.functional.LazyObject, django.utils.functional.lazy() 或 lambda.。

更多关于Django settings的设置方法请参考公众号文章：《25、Django开发总结：settings.py设置选项详解》

函数和方法

1. 函数和方法应该尽可能短小，只做一件事情。

2. 函数和方法的参数应该少于5个，参数之间应该使用逗号分隔。

3. 函数和方法应该有明确的返回值，如果没有返回值应该使用None。

数据库

1. 模型的字段应该使用小写字母和下划线分隔，避免使用特殊字符和空格。

2. 模型应该使用verbose_name和verbose_name_plural属性来指定模型的名称和复数形式。

3. 模型应该使用related_name属性来指定反向关系的名称。

安全

1. 避免使用eval和exec等危险函数。

2. 避免使用不安全的SQL查询，应该使用参数化查询和ORM查询。

3. 避免使用明文密码和敏感信息，应该使用加密和哈希函数进行处理。

测试

1. 测试应该覆盖所有的代码路径，包括异常情况和错误处理。

2. 测试应该使用单元测试和集成测试来保证代码的正确性和稳定性。

3. 测试应该使用mock和fixture来模拟测试环境和数据。

其他项

  • 标记所有字符串以进行国际化，国际化时按规范标记所有需要翻译的字符串，有关详细信息，请参阅i18n文档。
  • 删除在更改代码时不再使用的导入语句。此任务最常用的工具是pyflakes和pylint。
  • 系统地从代码中删除所有尾部空白，因为这些空白会添加不必要的字节，给补丁添加视觉混乱，偶尔还会导致不必要的合并冲突。一些IDE可以配置为自动删除它们，大多数VCS工具可以设置为在diff输出中突出显示它们。然而，请注意，只删除空白（或只为标称的PEP 8一致性进行更改）的补丁可能会被拒绝，因为它们只引入噪声而不是代码改进。下次在该区域更改代码时，请整理好。
  • 请不要在您贡献的代码中输入您的姓名。策略是将贡献者的名字保存在与Django一起分发的AUTHORS文件中，而不是分散在整个代码库中。

最后，关于编码规范开发辅助类的工具使用，参考下篇文章：企业开发中的编码规范校验和代码提交规范校验工具使用。介绍pre-commit、pep8编码规范检查工具flake8、导包规范工具isort、删除不再使用的导入语句pyflakes、pylint等工具的实际使用。

参考资料


  • Django官方规范指南：https://docs./en/dev/internals/contributing/writing-code/coding-style/
  • JavaScript规范指南：https://docs./en/dev/internals/contributing/writing-code/javascript/
  • PEP 8规范指南：https://peps./pep-0008/
  • pep8检查工具：https://pypi./pypi/pep8

Django专栏

https://blog.csdn.net/zhouruifu2015/category_5959525.html

更多精彩，关注我公号，一起学习、成长

图片

    本站是提供个人知识管理的网络存储空间，所有内容均由用户发布，不代表本站观点。请注意甄别内容中的联系方式、诱导购买等信息，谨防诈骗。如发现有害或侵权内容，请点击一键举报。
    转藏 分享 献花（0）

    来自： 汉无为 > 《Python》

    举报/认领

    0条评论

    发表

    请遵守用户 评论公约

    类似文章 更多