跳到主要内容

8.3 文档维护规范

本页面向维护 DLZ-DB 文档的开发者。所有修改先遵守 事实来源，再按本页检查结构、示例和链接。

1. 分层职责​

  • 根 README.md：项目价值、最短上手和文档入口。
  • llms.txt：AI 对项目全貌的快速认识和路由，不承担编程细节。
  • docs/README.md：面向人的唯一完整目录。
  • docs/5.AI辅助/dlz-db-速读.md：唯一 AI 编程契约。
  • docs/1–4：产品、上手、使用和框架集成教程。
  • docs/6.参考手册：精确 API、配置、注解、边界和限制。
  • docs/7.版本迁移：只保留迁移到当前版本仍有执行价值的内容。
  • docs/8.维护者文档：架构、事实来源、维护规范和内部实现说明。

一个事实只能有一个完整维护位置。其他页面保留局部示例或一句摘要，并链接到唯一主题页。

2. API 和包边界​

  • 业务示例只使用 API、SPI 与实现边界 列出的稳定 API。
  • 面向业务用户的 Java 代码块不得 import com.dlz.db.internal.*。
  • internal 类型只能在维护者正文中作为实现事实讨论，不能作为推荐参数、返回类型或扩展示例。
  • IDE 中可见的 public 类不自动成为稳定 API。
  • 新 SPI 必须先有真实调用点和机制测试，再写入参考手册。

3. 当前 API 易错项​

撰写或审查示例时重点检查：

  • 静态入口为 DB.pojo/table/jdbc/sql/batch/ds/tx/config，字段名小写。
  • Wrapper 入口为 selectWrapper/insertWrapper/updateWrapper/deleteWrapper。
  • 查询列使用 .select(...)，不是 .columns(...)。
  • 复合条件使用 .ands(...) 和 .ors(...)，不是 .and(...)、.or(...)。
  • 分页使用 .page(...).queryBeanPage()、.queryPage() 或直接 DB.jdbc.page(..., PageRequest.of(...), ...)。
  • Page 位于 com.dlz.db.model，数据字段是 records。
  • count() 返回 long。
  • DB.batch.* 返回 BatchResult，成功判断使用 isSuccess()。
  • DB.jdbc 使用 ?；DB.sql 和条件 sql() 使用 #{key}。
  • 直接 CRUD 已立即执行；UPDATE/DELETE Wrapper 以 .execute() 结束。
  • 数据库自增主键显式使用 IdType.AUTO；@TableId 默认是 SEQ。
  • Spring Boot 不生成或继承 SpringDlzDbConfig 等历史配置类。

旧名称可以在迁移文档的“旧 API”列中出现，但必须同时给出当前替代方法，不能放在可复制的当前示例中。

4. 安全边界必须写清​

以下限制不可为了缩短教程而省略：

  • UPDATE/DELETE Wrapper 必须有明确业务条件；逻辑删除条件会使空 WHERE 保护不再等价于业务条件保护。
  • ${key} 只能用于白名单 SQL 结构，不能接收普通用户输入。
  • 多数据源切换不是分布式事务。
  • 自动表结构更新不适合生产环境。
  • JDBC 自动 count 不保证复杂 SQL 正确。
  • show-caller 写入 MDC，最终展示依赖日志 pattern。

5. 版本、兼容性和数字​

  • 当前版本和依赖版本从 POM 取得，不从旧 README 或历史报告复制。
  • Java 产物目标、完整构建 JDK 和 CI 验证矩阵是三个不同概念，分别从 POM 与 workflow 核对。
  • 测试数、覆盖率、性能和代码行数必须附带日期、版本、commit 和执行环境。
  • 常驻 README、AI 文档和教程不手写会随测试变化的数字；发布证据放入 CI 产物或发行附件，不提交带日期的历史报告目录。
  • 版本迁移目录只保留迁移到当前版本仍有执行价值的内容；Git 历史负责追溯旧文档。

6. 配置文档​

  • 配置键、类型和默认值逐项与 DlzDbProperties 对齐。
  • 区分“能够绑定”和“当前执行路径真实读取”；未消费字段不得描述为已生效功能。
  • Spring/Solon 文档只补充框架特有的数据源和自动装配差异，完整 DLZ-DB 配置集中在 配置参考。
  • 示例默认采用生产安全值；开发环境的便利配置必须明确标注风险。

7. AI 文档​

  • llms.txt 只描述全貌、模块和路由。
  • 入口选择、硬约束、代码模板和禁止生成项只在 AI 编程速读中完整维护一次。
  • 工具配置页只说明如何加载文档，不为 Cursor、Copilot、JetBrains 等分别复制一套 API Prompt。
  • 任务指南只补充该任务特有的流程，公共 CRUD 规则链接回 AI 编程速读。

8. 链接和示例​

  • 本地链接使用相对路径，移动文件后全仓搜索旧路径。
  • 标题层级连续，代码围栏成对闭合并标注正确语言。
  • 通用 Java 片段至少兼容 Java 8，不使用文本块、Map.of 等高版本语法。
  • 示例应能够编译；涉及 SQL 行为、安全或事务的示例还应有测试。
  • 教程中的完整应用优先引用可运行 Demo，避免维护第二套近似源码。

9. 修改流程​

  1. 确定变化属于 API、配置、框架集成、迁移还是实现细节。
  2. 从源码、POM、元数据和测试确认事实。
  3. 先修改唯一主题页，再修改需要该信息的局部教程。
  4. 同步 AI 编程速读，但不把完整参考表复制到 llms.txt。
  5. 搜索旧类名、包名、方法名、版本号和旧路径。
  6. 检查用户示例没有 internal import。
  7. 检查 Markdown 链接、围栏和标题。
  8. 运行相关测试；发布前执行完整 CI 等价命令。

10. 建议的自动校验​

文档检查应逐步进入 CI：

  • 从 POM 校验当前版本、坐标、Java release 和模块。
  • 从配置类校验配置键与默认值。
  • 编译文档中的标记 Java snippet，或从已编译的 snippet 源同步到 Markdown。
  • 禁止用户文档代码块 import internal。
  • 对 8.0 API 基线执行 Revapi 或 japicmp 兼容性比较。
  • 检查稳定 public/protected 签名是否新增 internal 泄漏。
  • 检查本地链接、Markdown 围栏和禁止的旧 API。
  • 禁止常驻文档出现无基线的测试数与覆盖率。

自动化应直接读取现有事实源，不再创建一份手工同步的项目元数据文件。