Become a sponsor
文档规范
概述
良好的文档是项目可维护性的基石。本文规范 API 文档、Form 文档、代码注释等文档的编写标准。
文档原则
- 文档与代码同步更新
- 使用中文编写（项目约定）
- 示例代码可直接运行
API 接口文档
Django 项目通过代码注释和文档站点提供 API 文档。所有接口定义在各模块的 urls.py 中，视图类的 docstring 描述接口用途。
View 文档注释
python
@method_decorator(check_login, name="post")
class ExampleAddView(PermissionRequired, View):
"""
添加案例视图
处理POST请求，创建新的案例记录。
URL: /example/add
请求方法: POST
权限要求：sys:example:add
请求参数（JSON Body）：
- name: 案例名称（必填，1-100字符）
- avatar: 案例图片（可选）
- type: 案例类型（必填，1-4）
- status: 案例状态（必填，1-正常 2-禁用）
- sort: 排序权重（必填）
"""
permission_required = ("sys:example:add",)
@operation_log(title="案例管理-添加记录", log_type=LogType.ADD)
def post(self, request):
result = services.add_example(request)
return result文档层级
- 类 docstring：接口说明（URL、方法、权限、参数）
- 方法 docstring：处理流程说明
- 行内注释：关键逻辑说明
Form 文档
Django ModelForm 通过 error_messages 参数定义中文错误提示，通过 help_text 和 verbose_name 提供字段说明：
python
class ExampleForm(forms.ModelForm):
"""案例表单验证类"""
# 案例名称（必填，1-100字符）
name = forms.CharField(
required=True,
max_length=100,
error_messages={
'required': '案例名称不能为空',
'max_length': '案例名称长度不得超过100个字符',
}
)
# 案例类型（1-类型1 2-类型2 3-类型3 4-类型4）
type = forms.IntegerField(
required=True,
min_value=1,
max_value=4,
error_messages={
'required': '案例类型不能为空',
'min_value': '案例类型值不能小于1',
'max_value': '案例类型值不能大于4',
}
)
class Meta:
model = models.Example
fields = ['name', 'avatar', 'type', 'status', 'sort']error_messages 规范
- 必须填写所有验证规则的中文错误提示
- 枚举值说明使用
值-含义格式（如1-正常 2-禁用） - 有约束条件时在描述中说明（如
1-100字符）
代码注释规范
模块注释
python
"""
案例管理服务模块
=============================================================
该模块实现了案例管理相关的所有业务逻辑。
包括案例的分页查询、详情查询、添加、更新、删除等功能。
"""方法注释
python
def get_example_page(request):
"""
查询案例分页数据
Args:
request: HttpRequest对象，包含查询参数
- pageNo: 当前页码（可选，默认为1）
- pageSize: 每页记录数（可选，默认为PAGE_SIZE）
- name: 案例名称（可选，模糊查询）
Returns:
R: 包含分页数据的JSON响应
"""行内注释
python
# 构建基础查询（只查询未删除的记录）
query = Example.objects.filter(is_delete=False)注释原则
- 解释"为什么"而非"是什么"
- 复杂逻辑必须注释
- 简单代码无需注释
- 注释与代码同步更新
文档目录结构
wiki/ # VitePress 文档站
├── zh/ # 中文文档
│ ├── 1. 了解项目/ # introduction.md, why.md, struct.md, course.md
│ ├── 2. 快速入门/ # volume1/（环境、启动、数据库、Docker）
│ ├── 3. 模块开发实战/ # volume2/（Model→Form→Service→View→URL→前端）
│ ├── 4. 架构设计/ # volume3/（分层、基类、缓存、安全）
│ ├── 5. 开发指南/ # volume4/
│ │ ├── 5.1 后端核心功能/ # core/（JWT、RBAC、字典、日志、限流）
│ │ ├── 5.2 后端业务模块/ # business/（用户、角色、菜单、文章、任务）
│ │ ├── 5.3 后端通用工具/ # tools/（上传、Excel、IP/UA、密码、富文本）
│ │ ├── 5.4 前端开发/ # frontend/（组件、路由、Store、构建）
│ │ └── 5.5 前后端联调/ # integration/（代理、权限、上传、字典）
│ ├── 6. 代码生成器/ # volume5/（CLI、Web UI、模板）
│ ├── 7. 运维部署/ # volume6/（Docker、Nginx、Supervisor、监控）
│ └── 8. 规范标准/ # volume7/（API 响应、分页、Git、测试、文档）前端文档结构
前端相关文档分布在以下位置：
| 文档 | 路径 | 说明 |
|---|---|---|
| 前端页面规范 | volume7/fe-component.md | 页面结构、组件使用、命名规范 |
| 前端 API 规范 | volume7/fe-api.md | API 文件组织、函数命名、请求规范 |
| 公共组件库 | volume4/frontend/components.md | 组件列表、Props、Events、用法 |
| 前端构建 | volume4/frontend/build.md | Vite 配置、环境变量、Nginx 部署 |
| API 层开发 | volume4/frontend/api.md | API 层开发指南 |
| 页面视图开发 | volume4/frontend/view.md | 页面视图开发指南 |
文档更新检查清单
- [ ] 新增/修改 API 接口时，同步更新 View 类的 docstring
- [ ] 新增/修改 Form 字段时，填写
error_messages中文提示 - [ ] 复杂逻辑添加代码注释
- [ ] 重大变更更新 wiki 文档
总结
文档规范覆盖 API 文档（View docstring）、Form 文档（error_messages）、代码注释（文件头/模块/方法/行内）。核心原则：文档与代码同步更新，使用中文编写，示例可直接运行。重大变更同步更新 wiki 文档。