文档规范

概述

良好的文档是项目可维护性的基石。本文规范 API 文档、Pydantic 文档、代码注释等文档的编写标准。

文档原则

• 文档与代码同步更新
• 使用中文编写（项目约定）
• 示例代码可直接运行

API 接口文档

Tornado 自动生成 Swagger 文档，访问地址：

http://127.0.0.1:8041/docs        # Swagger UI
http://127.0.0.1:8041/redoc       # ReDoc
http://127.0.0.1:8041/openapi.json # OpenAPI JSON

Handler 文档注释

class PositionAddHandler(BaseHandler):
    @permission_required("sys:position:add")
    @check_demo
    @operation_log("岗位管理", "添加")
    async def post(self):
        """新增岗位

        - **name**: 岗位名称（必填，1-150字符）
        - **status**: 岗位状态（必填，1-在用 2-停用）
        - **sort**: 岗位排序（必填，0-99999）
        """
        return await position_service.add(self)
    """
    return await position_service.add(request, data)

文档层级

• summary：简短标题（显示在接口列表）
• docstring：详细描述（显示在接口详情）
• Pydantic Field(description=...)：字段级描述

Pydantic 文档

Pydantic 模型通过 Field 的 description 参数自动生成字段文档：

class PositionForm(BaseSchema):
    """岗位创建/编辑表单"""

    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="岗位排序"
    )

description 规范

• 必须填写 description，用于 Swagger 文档展示
• 枚举值说明使用 值-含义 格式（如 1-在用 2-停用）
• 有约束条件时在描述中说明（如 1-150字符）

代码注释规范

文件头注释

# +======================================================================
# | 模块: 岗位业务逻辑层
# | 说明: 岗位的增删改查、唯一性校验、状态管理等业务处理
# +======================================================================

类注释

class PositionService(BaseService(Position]):
    """岗位业务服务类，继承基础服务获得通用 CRUD 能力"""

方法注释

def _before_delete(self, ids) -> Optional[str]:
    """删除前校验：存在用户引用该岗位时禁止删除，避免用户岗位悬空

    Args:
        ids: 逗号分隔的ID字符串

    Returns:
        None: 放行删除
        str: 拦截删除，返回错误提示
    """

行内注释

# 自动软删过滤，调用方无需关心 is_delete
query = query.filter(self._soft_col() == 0)

注释原则

• 解释"为什么"而非"是什么"
• 复杂逻辑必须注释
• 简单代码无需注释
• 注释与代码同步更新

文档目录结构

document/                           # 补充文档
├── 数据库迁移_runbook.md           # 数据库迁移操作手册
└── djangoadmin.tornado.antdvue.sql  # 数据库结构 SQL

wiki/                               # VitePress 文档站
├── zh/                             # 中文文档
│   ├── 1. 了解项目/                # why.md, struct.md, course.md
│   ├── 2. 快速入门/                # volume1/（环境、启动、数据库、Docker）
│   ├── 3. 模块开发实战/            # volume2/
│   ├── 4. 架构设计/                # volume3/
│   ├── 5. 开发指南/                # volume4/
│   │   ├── 5.1 后端核心功能/       #   core/
│   │   ├── 5.2 后端业务模块/       #   business/
│   │   ├── 5.3 后端通用工具/       #   tools/
│   │   ├── 5.4 前端开发/           #   frontend/
│   │   └── 5.5 前后端联调/         #   integration/
│   ├── 6. 代码生成器/              # volume5/
│   ├── 7. 运维部署/                # volume6/
│   └── 8. 规范标准/                # volume7/

前端文档结构

前端相关文档分布在以下位置：

文档	路径	说明
前端页面规范	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 文档。