djangoadmin/djangoadmin-wiki

Fork 0

Files

T

gitadmin 23bd737b82 优化更新

2026-09-13 23:01:19 +08:00

6.0 KiB

Raw Blame History

文档规范

概述

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

:::tip 文档原则

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

API 接口文档

建议使用 Postman 或 Apifox 等工具维护 API 文档。

Router 文档注释

@position_blue.route('/add', methods=['POST'])
@check_permission('sys:position:add')
def add():
    """
    新增岗位

    请求参数:
        - name: 岗位名称（必填，1-150字符）
        - status: 岗位状态（必填，1-在用 2-停用）
        - sort: 岗位排序（必填，0-99999）

    :return: 添加结果响应
    """
    from src.modules.system.position.service import add_position
    from src.modules.system.position.schema import PositionForm
    data = parse_request_body(request, PositionForm)
    return add_position(data)

:::tip 文档层级

函数名：简短标题
docstring：详细描述（请求参数、返回值）
WTForms 字段：字段级描述 :::

WTForms 文档

WTForms 表单通过字段的 label 参数和 validator 的 message 参数提供文档信息：

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

    name = StringField('岗位名称', validators=[
        DataRequired(message='岗位名称不能为空'),
        Length(min=1, max=150, message='岗位名称长度必须在1-150个字符之间')
    ])
    status = IntegerField('岗位状态', validators=[
        DataRequired(message='岗位状态不能为空'),
        NumberRange(min=1, max=2, message='岗位状态必须是1或2')
    ])
    sort = IntegerField('岗位排序', validators=[
        DataRequired(message='岗位排序不能为空'),
        NumberRange(min=0, max=99999, message='岗位排序必须在0-99999之间')
    ])

:::tip 文档规范

label：字段中文名，用于前端显示
message：校验失败提示，用于返回给用户
枚举值说明使用 值-含义 格式（如 1-在用 2-停用）
有约束条件时在 message 中说明（如 1-150字符） :::

代码注释规范

文件头注释

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

类注释

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

方法注释

@classmethod
def before_delete(cls, ids):
    """
    删除前校验：存在用户引用该岗位时禁止删除

    Args:
        ids: 待删除的岗位ID列表

    Raises:
        BizError: 岗位被用户引用时抛出
    """
    for pid in ids:
        if UserRepository.count_by({'position_id': pid}) > 0:
            raise BizError(f"岗位ID {pid} 已被用户引用，无法删除")

行内注释

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

:::tip 注释原则

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

文档目录结构

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

wiki/                               # VitePress 文档站
├── zh/                             # 中文文档
│   ├── 1. 了解项目/                # why.md, struct.md, course.md
│   ├── 2. 快速入门/                # volume1/（环境、启动、数据库、Docker）
│   ├── 3. 模块开发实战/            # volume2/（Model→Schema→Repo→Service→Router→前端）
│   ├── 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 接口时，同步更新 Router 注释
新增/修改 WTForms 字段时，填写 label 和 message
复杂逻辑添加代码注释
重大变更更新 wiki 文档

总结

文档规范覆盖 API 文档（Router 注释）、WTForms 文档（字段 label 和 message）、代码注释（文件头/类/方法/行内）。核心原则：文档与代码同步更新，使用中文编写，示例可直接运行。重大变更同步更新 wiki 文档。

6.0 KiB Raw Blame History Unescape Escape