# python代码规范 **Repository Path**: mtoooo/python-code-specification ## Basic Information - **Project Name**: python代码规范 - **Description**: 代码规范 - **Primary Language**: Python - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2021-03-04 - **Last Updated**: 2021-03-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README --- # 主题列表：juejin, github, smartblue, cyanosis, channing-cyan, fancy, hydrogen, condensed-night-purple, greenwillow, v-green, vue-pro, healer-readable, mk-cute, jzman, geek-black, awesome-green, qklhk-chocolate # 贡献主题：https://github.com/xitu/juejin-markdown-themes theme: github highlight: github --- > 写在前面 - 文档是对Python基本规范(PEP8)的一些补充，代码必须满足基本规范PEP8以后，还需要满足本规范 - 所有规范都基于一个原则：简洁高效，如果你认为自己写的不够简洁，不够高效，那么必定不符合本规范 - STRUCTURE.md为项目结构文件，每次提交代码必须检查是否需要更新 - 添加或者删除接口一定先修改接口文档 - 欢迎对代码规范进行补充 > Ctrl+ALt+l召唤PEP8 ### 代码规范 #### 接口版本管理 > 接口版本v1、v2... > 通过接口版本管理，利于接口的重构和项目大的更新以及迁移 v1.py ```python path_url = "v1" url_service = { "auth": path(path_url, include(api_auth.urls)), ... } ``` v2.py ```python path_url = "v2" url_service = { "auth": path(path_url, include(api_auth.urls)), ... } ``` urls.py ```python form config.routes.v1 import url_service as v1 form config.routes.v2 import url_service as v2 urlpatterns = [] url_path = "" if url_version == "v1": urlpatterns += v1 if url_version == "v2": urlpatterns += v2 ``` #### swagger接口管理 `django 2.0及以上` - 安装 ```shell pip install django-rest-swagger ``` - settings ```shell INSTALLED_APPS = [ ... 'rest_framework_swagger', ] ``` - view.py > class view ，"""三引号内注明接口名称。请求`required`中可以查看请求字段`memo`该字段的数据类型`str`和该字段的说明`流水编号`。响应`Response`给了返回数据的标准格式，`view`继承`django-rest-framework`的`APIView`可以使用`self.response_result`作为返回数据，标准格式为`{"code": 200,"detail": "success","data": []}` 自定义状态码`Http Code | detail` `13001`例如`withdrew is error` ``` class AccountView(BetterCreateModelMixin, viewsets.GenericViewSet): def create(self, request, *args, **kwargs): """ 增加withdraw地址: required: memo(str): 流水编号 Response: { "code": 200, "detail": "ok", "data": { } } Http Code | detail 200 | ok 13504 | invalid withdraw address 13505 | not allow add user own deposit address 13000 | param error """ ``` #### 命名规范 - 文件名 所有文件、文件夹使用`小写字母+下划线`命名 - 常量 常量命名使用`全大写＋下划线` - 普通变量 `小写字母+下划线`必须是名词 - 函数名 `小写字母＋下划线`而且函数第一个单词必须是动词 - 类 大驼峰的形式`UserManagement` #### settings规范 > 将dev_settings设置.gitignore，不提交供本地开发使用 settings.py中添加 ```python try: # 使用本地环境变量 from .dev_settings import * except ImportError: # 线上无dev使用正式配置 from .local_settings import * ``` - local_settings 正式配置文件，`token`,`key`,`数据库`连接信息等 - dev_settings设置 开发使用本地环境 - INSTALLED_APPS, MIDDLEWARE等变量的赋值需要分类django,application,other... #### Models规范 - model命名 类命名+`Molde` ，例如：`AccountModel`;`HistoryModel` 以英文名词命名,尽量简洁 - Meta `verbose_name`: 中文名词,言简意赅 `verbose_name_plural`:同`verbose_name` `db_table`: 项目名+Model名，格式必须为`小写英文+下划线`。例如：`taro_account_log` - 字段 `小写英文+下划线`，例如`id,name,password,is_super,is_delete,create_time` `verbose_name`参数必须赋值，方便阅读 使用`Foreign Key`时，必要设置`on_delete=models.CASCADE`级联删除,例如：`account = models.ForeignKey(AccountModel, verbose_name="name", on_delete=models.CASCADE, unique=True)` 长度设置`max_length=50` 唯一索引`unique=True` 是否为空`blank=True`存储空字符串, `null=True`数据库上表现`NULL`,日期型（DateField、TimeField、DateTimeField）和数字型（IntegerField、DecimalField、FloatField）不能接受空字符串,则需同时设置`blank=True, null=True` - admin 后台管理站点显示字段 `admin.site.site_header` `admin.site.site_title` `admin.site.index_title` admin_model 显示字段`list_display = ['id', 'name', 'type_no', 'src', 'side', 'dev_no', 'content', 'level', 'occ_time']` 支持搜索字段`search_fields = ['name', 'type_no', 'src', 'side', 'dev_no', 'content', 'bit', 'level', 'occ_time']` 日期排序`date_hierarchy = 'occ_time'` 外键默认值`raw_id_fields` #### url规范 - `小写英文+横杠(-)` - 使用名词，不能使用get、post等，动词可以通过接口的method体现 - 每个URL后面需要注释 #### views规范 - `大驼峰英文+View`命名 - 规范使用method`post` `delete` `put` `get` `增删改查` - 规范注释`"""`三引号注明`view`作用 - 规范接口返回数据`{"code": 200, "detail": "success", "data":[]}`,返回状态码放到`code`描述放到`detail`里 - 如果用到filter，django_filter的class需要写在对应app的filters.py里 ```python class AccountView(APIView): def post(self, request, *args, **kwargs): """创建用户 """ pass def delete(self, request, *args, **kwargs): """删除用户 """ pass def put(self, request, *args, **kwargs): """修改用户 """ pass def get(self, request, *args, **kwargs): """查询用户 """ pass ``` #### serializers规范 - 参考链接 [https://www.django-rest-framework.org/api-guide/serializers/#declaring-serializers](https://www.django-rest-framework.org/api-guide/serializers/#declaring-serializers) - 声明序列化器 ```python from datetime import datetime class Comment: def __init__(self, email, content, created=None): self.email = email self.content = content self.created = created or datetime.now() comment = Comment(email='leila@example.com', content='foo bar') ``` ```python from rest_framework import serializers class CommentSerializer(serializers.Serializer): email = serializers.EmailField() content = serializers.CharField(max_length=200) created = serializers.DateTimeField() ``` - 序列化对象 ```python serializer = CommentSerializer(comment) serializer.data # {'email': 'leila@example.com', 'content': 'foo bar', 'created': '2016-01-27T15:17:10.375877'} ``` ```python from rest_framework.renderers import JSONRenderer json = JSONRenderer().render(serializer.data) json # b'{"email":"leila@example.com","content":"foo bar","created":"2016-01-27T15:17:10.375877"}' ``` - 反序列化对象 ```python import io from rest_framework.parsers import JSONParser stream = io.BytesIO(json) data = JSONParser().parse(stream) ``` ```python serializer = CommentSerializer(data=data) serializer.is_valid() # True serializer.validated_data # {'content': 'foo bar', 'email': 'leila@example.com', 'created': datetime.datetime(2012, 08, 22, 16, 20, 09, 822243)} ``` - 保存实例 ```python class CommentSerializer(serializers.Serializer): email = serializers.EmailField() content = serializers.CharField(max_length=200) created = serializers.DateTimeField() def create(self, validated_data): return Comment(**validated_data) def update(self, instance, validated_data): instance.email = validated_data.get('email', instance.email) instance.content = validated_data.get('content', instance.content) instance.created = validated_data.get('created', instance.created) return instance ``` #### import规范 - 将import都放在头部 - 分行书写 ```python # yes import os import sys # no import sys,os # yes from subprocess import Popen, PIPE ``` - 避免使用相对路径`.` `..` ```python # yes from foo.bar import Bar # no from ..bar import Bar ``` #### CMS规范 - 接口统一在`cms/api`下，避免使用非管理平台的script、serializers和filter. ### 工具推荐 - Eolonker接口管理[https://www.eolinker.com/](https://www.eolinker.com/) - 墨刀原型设计[https://www.modao.cc/](https://www.modao.cc/) - 蓝湖Axure客户端[https://lanhuapp.com/prd/?axure](https://lanhuapp.com/prd/?axure) - TAPD敏捷开发管理[https://www.tapd.cn/](https://www.tapd.cn/) - 禅道工单管理，适合内网部署[https://www.zentao.net/](https://www.zentao.net/) - 安居客PEP8代码规范[https://github.com/anjuke/coding-style/blob/master/python/python-coding-style.md](https://github.com/anjuke/coding-style/blob/master/python/python-coding-style.md)