182 lines
6.1 KiB
Markdown
182 lines
6.1 KiB
Markdown
# 文档规范
|
||
|
||
## 概述
|
||
|
||
良好的文档是项目可维护性的基石。本文规范 API 文档、Form 文档、代码注释等文档的编写标准。
|
||
|
||
:::tip 文档原则
|
||
- 文档与代码同步更新
|
||
- 使用中文编写（项目约定）
|
||
- 示例代码可直接运行
|
||
:::
|
||
|
||
## 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
|
||
```
|
||
|
||
:::tip 文档层级
|
||
- 类 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']
|
||
```
|
||
|
||
:::tip 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)
|
||
```
|
||
|
||
:::tip 注释原则
|
||
- 解释"为什么"而非"是什么"
|
||
- 复杂逻辑必须注释
|
||
- 简单代码无需注释
|
||
- 注释与代码同步更新
|
||
:::
|
||
|
||
## 文档目录结构
|
||
|
||
```
|
||
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 文档。
|