文档维护规范

目录与归属规则

  • app/ 和 admin/ 是两个独立文档包,各自的 README.md 只维护接口目录;按业务模块建子目录,每个接口独立写入 <module>/<action>.md,禁止在一份 MD 中合并多个接口。
  • 一个接口以 HTTP 方法和路径确定;同一路径的不同方法分别建文件,例如 create.md、get.md、update.md。公共规则文档不承载多个业务接口的完整契约。
  • 公共协议只维护在 common.md,各模块通过链接引用;同一接口只有一份完整契约,需要跨端复用时链接原文并说明可用权限。
  • 先明确接口供 App、管理后台还是两端共用,再更新对应目录。管理后台接口必须单独说明管理员身份与权限,不以页面隐藏作为权限校验。
  • 每项接口标明 待设计、已实现 或 已联调,并注明适用环境和验证范围。接口存在、服务已部署、客户端已接入分别描述。
  • 部署描述统一采用“唯一正式部署环境,当前处于上线前阶段”,不再把当前服务器称为测试服或开发服;local/dev/prod 仅用于说明程序配置及功能条件。历史测试结果保留实际日期和范围,不能因名称更正扩大验收结论。上线前清库计划见接入入口。
  • 当前App登录注册及后台首期接口已实现,新增资料编辑和相册以对应接口状态为准;供应商与HTTPS状态见认证文档。待设计内容不填写虚构URL、请求字段或Token协议;UI演示不能作为已实现接口的证据。
  • 业务接口与框架运维接口分别管理。/actuator/* 不作为管理后台业务接口,local 演示不作为 App 正式接口。
  • API 契约随 Java 代码维护在当前仓库;跨项目架构与部署说明保留在全局文档,项目进度仍只在全局当前进度更新。

单个接口必须说明的内容

  1. 业务用途、调用端、状态、关联页面或流程。
  2. HTTP 方法、完整路径、适用环境及认证/权限要求。
  3. 请求头、路径参数、查询参数、请求体;逐字段写明名称、类型、必填、允许值、长度限制和示例。没有参数时明确写“无”。 请求头引用公共请求头,明确版本、渠道、设备与请求追踪字段是否强制校验;示例需完整写出必填项。
  4. HTTP 状态和响应字段,包括类型、可空性、枚举、分页或排序语义;尚未定义的规则不当成既有协议。
  5. 成功与适用的失败示例,列出业务错误码及处理建议。
  6. 最小调用示例、实现依据和实际验证方式;涉及密码等敏感值时只用占位符。

新增、调整、废弃接口时同步修改契约及所属目录;涉及不兼容修改时说明版本和客户端迁移方式。文档更新后检查相对链接、JSON 示例及与代码的一致性。

接口与字段兼容规范

后台接口另须说明管理员认证、所需操作权限、可访问的数据范围和敏感字段展示规则;写操作说明审计范围及并发冲突处理。菜单可见、X-Client-Type=admin和App登录状态都不等同于管理员授权。规划中的功能仅在后台目录标注待实现,确认真实契约后再创建具体接口文件。

  • 既有 /api/v1/ 方法、路径、字段和状态码保持稳定;代码分包、数据库列名或存储方式变化不自动改变公开契约。
  • 新接口按业务资源组织路径,明确调用端与环境,读取使用GET;创建、修改、删除按实际语义选择方法。刷新、完成注册等已发布动作保留原路径,不为统一命名强制迁移旧客户端。
  • 请求、响应使用独立DTO,数据库模型不直接序列化为接口返回。新增数据库列不自动出现在JSON;公开字段采用现有camelCase规则。
  • 新增请求字段优先可选,省略时保持旧行为;新增响应字段前确认客户端能忽略未知字段。字段改名、类型改变、可空性收紧、枚举含义改变、必填项增加和删除字段均按不兼容变更处理,不能在原版本直接替换。
  • 每个部分更新接口逐字段说明“不传、null、空字符串、空列表”的含义。当前注册草稿不传或null保留原值,avatarId空字符串清除绑定,interests空列表清空;这一规则不能推断为所有未来PATCH接口的通用规则。
  • 新字段默认UUID用字符串、生日用YYYY-MM-DD、时间点用带时区的ISO 8601字符串;已有票据expiresAt等Unix毫秒字段保留原协议并注明单位。大小必须注明字节或MiB,长度必须注明具体计数方式,不能把字数、UTF-16长度和字节数混为一谈。
  • JSON使用公共code/message/data/errors结构,HTTP状态与业务码共同判断;固定code不翻译,提示和字段错误补齐四语。文件、WebSocket和网关拦截按各自已发布协议处理。
  • 认证、角色、资源归属、公共请求头、HTTPS与JWE校验范围必须写明,客户端自报设备或平台不授予权限。写操作的超时/网络失败不能自动视为未执行;未实现业务幂等的接口不宣称可安全自动重试。
  • 分页、排序和删除策略在相关业务开发时定义并验证。当前没有统一分页、通用删除或账号注销协议,不预留可调用的空实现或虚构返回值。

2026-11-20上线前媒体协议例外:用户明确确认产品尚未上线、无需旧App兼容,因此本次在现有路径统一RoutedMediaDelivery并取消能力头选择,删除旧下载项delivery/message。该授权仅针对本次App媒体响应,不推导为其他业务或后台协议可以随意破坏兼容;源码、后端部署与Flutter同步状态分别记录,见统一媒体交付。

废弃字段或接口时先列出替代方案、受影响客户端和兼容发布阶段;先让服务停止依赖旧字段,再完成调用方迁移,最后通过独立数据库迁移移除列。应用回退不能恢复被删数据,不能把代码回退当成数据库回退。

自动检查与验收范围

服务器构建时,ApiDocumentationTest对照编译后的HTTP控制器检查方法/路径与独立接口MD一一对应,并检查必需章节、元数据、所属端目录与导航。测试包括条件启用的控制器;仅local演示接口不进入公开目录,WebSocket握手另按连接测试验收。

自动检查不证明字段含义和业务规则正确。修改接口仍需验证成功、错误、鉴权、字段边界、资源归属及相关并发路径;数据库变更同时检查迁移、旧数据兼容和事务。发布说明分别列出自动测试、真实服务、实际客户端及未验证范围。

页面组织

  • 接口页使用固定顺序:请求参数 → 请求示例 → 成功响应 → 失败响应 → 接入说明;相关公共规则通过链接引用。
  • 文件开头的 YAML 元数据维护 heading、description、method、path、auth 和 status,网站据此显示标题和接口概要;元数据同样须与真实接口一致。
  • App/后台目录页按功能模块列接口索引;mkdocs.yml使用“调用端 → 功能模块 → 独立接口”的层级,新增接口必须放入对应模块,不再平铺在App或后台一级目录下。新功能增加模块,已有接口归入现有模块,每个接口只出现一次。
  • 左侧模块可展开/收起,默认展开当前页面的祖先模块并标记当前接口;搜索匹配模块名、接口标题、HTTP方法和路径,自动展开命中分支,清空后恢复原折叠状态。调整导航不移动接口MD或改变业务URL,原分享链接继续可用。
  • 文档站统一使用中文目录、深色背景、清晰的参数表与示例代码,保证正文、辅助文字和代码高亮的可读对比度;共用样式在 docs/theme/ 维护,不在每个接口文件复制 UI。
  • 发布命令为 bash deploy/docs/publish.sh,更新后检查公网页面、目录跳转、手机阅读和代码复制。部署内部说明不放入公开接口目录。