178 lines
5.8 KiB
Markdown
178 lines
5.8 KiB
Markdown
# 文档规范
|
||
|
||
## 概述
|
||
|
||
良好的文档是项目可维护性的基石。本文规范 API 文档、Pydantic 文档、代码注释等文档的编写标准。
|
||
|
||
:::tip 文档原则
|
||
- 文档与代码同步更新
|
||
- 使用中文编写（项目约定）
|
||
- 示例代码可直接运行
|
||
:::
|
||
|
||
## API 接口文档
|
||
|
||
FastAPI 自动生成 Swagger 文档，访问地址：
|
||
|
||
```
|
||
http://127.0.0.1:8031/docs # Swagger UI
|
||
http://127.0.0.1:8031/redoc # ReDoc
|
||
http://127.0.0.1:8031/openapi.json # OpenAPI JSON
|
||
```
|
||
|
||
### Endpoint 文档注释
|
||
|
||
```python
|
||
@router.post('/add', summary='添加岗位')
|
||
@permission_required("sys:position:add")
|
||
@check_demo
|
||
async def add(request: Request, data: PositionForm):
|
||
"""
|
||
新增岗位
|
||
|
||
- **name**: 岗位名称（必填，1-150字符）
|
||
- **status**: 岗位状态（必填，1-在用 2-停用）
|
||
- **sort**: 岗位排序（必填，0-99999）
|
||
|
||
:param request: FastAPI请求对象
|
||
:param data: 岗位表单数据
|
||
:return: 添加结果响应
|
||
"""
|
||
return await position_service.add(request, data)
|
||
```
|
||
|
||
:::tip 文档层级
|
||
- `summary`：简短标题（显示在接口列表）
|
||
- docstring：详细描述（显示在接口详情）
|
||
- Pydantic `Field(description=...)`：字段级描述
|
||
:::
|
||
|
||
## Pydantic 文档
|
||
|
||
Pydantic 模型通过 `Field` 的 `description` 参数自动生成字段文档：
|
||
|
||
```python
|
||
class PositionForm(BaseForm):
|
||
"""岗位创建/编辑表单"""
|
||
|
||
name: str = Field(
|
||
...,
|
||
min_length=1,
|
||
max_length=150,
|
||
description="岗位名称"
|
||
)
|
||
status: int = Field(
|
||
...,
|
||
ge=1,
|
||
le=2,
|
||
description="岗位状态：1-在用 2-停用"
|
||
)
|
||
sort: int = Field(
|
||
...,
|
||
ge=0,
|
||
le=99999,
|
||
description="岗位排序"
|
||
)
|
||
```
|
||
|
||
:::tip description 规范
|
||
- 必须填写 `description`，用于 Swagger 文档展示
|
||
- 枚举值说明使用 `值-含义` 格式（如 `1-在用 2-停用`）
|
||
- 有约束条件时在描述中说明（如 `1-150字符`）
|
||
:::
|
||
|
||
## 代码注释规范
|
||
|
||
### 文件头注释
|
||
|
||
```python
|
||
# +======================================================================
|
||
# | 模块: 岗位业务逻辑层
|
||
# | 说明: 岗位的增删改查、唯一性校验、状态管理等业务处理
|
||
# +======================================================================
|
||
```
|
||
|
||
### 类注释
|
||
|
||
```python
|
||
class PositionService(BaseService[Position]):
|
||
"""岗位业务服务类，继承基础服务获得通用 CRUD 能力"""
|
||
```
|
||
|
||
### 方法注释
|
||
|
||
```python
|
||
def _before_delete(self, ids) -> Optional[str]:
|
||
"""删除前校验：存在用户引用该岗位时禁止删除，避免用户岗位悬空
|
||
|
||
Args:
|
||
ids: 逗号分隔的ID字符串
|
||
|
||
Returns:
|
||
None: 放行删除
|
||
str: 拦截删除，返回错误提示
|
||
"""
|
||
```
|
||
|
||
### 行内注释
|
||
|
||
```python
|
||
# 自动软删过滤，调用方无需关心 is_delete
|
||
query = query.filter(self._soft_col() == 0)
|
||
```
|
||
|
||
:::tip 注释原则
|
||
- 解释"为什么"而非"是什么"
|
||
- 复杂逻辑必须注释
|
||
- 简单代码无需注释
|
||
- 注释与代码同步更新
|
||
:::
|
||
|
||
## 文档目录结构
|
||
|
||
```
|
||
document/ # 补充文档
|
||
├── 数据库迁移_runbook.md # 数据库迁移操作手册
|
||
└── djangoadmin.fastapi.elevue.sql # 数据库结构 SQL
|
||
|
||
wiki/ # VitePress 文档站
|
||
├── zh/ # 中文文档
|
||
│ ├── 1. 了解项目/ # why.md, struct.md, course.md
|
||
│ ├── 2. 快速入门/ # volume1/（环境、启动、数据库、Docker）
|
||
│ ├── 3. 模块开发实战/ # volume2/（Model→Schema→Repo→Service→Endpoint→前端）
|
||
│ ├── 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 接口时，同步更新 Swagger 注释
|
||
- [ ] 新增/修改 Pydantic 字段时，填写 `description`
|
||
- [ ] 复杂逻辑添加代码注释
|
||
- [ ] 重大变更更新 wiki 文档
|
||
|
||
## 总结
|
||
|
||
文档规范覆盖 API 文档（Swagger 自动注释）、Pydantic 文档（Field description）、代码注释（文件头/类/方法/行内）。核心原则：文档与代码同步更新，使用中文编写，示例可直接运行。重大变更同步更新 wiki 文档。
|