docs: 引入分层文档体系,删除 DEVELOPMENT.md
建立 docs/user/ 和 docs/development/ 分层文档结构: - docs/README.md 文档总路由、归属矩阵、影响分析规则 - docs/user/ 模板使用、配置、部署、故障排查 - docs/development/ 架构、后端、前端、构建发布开发规范 - README.md 轻量化为项目入口和索引 - 删除 DEVELOPMENT.md,内容拆分至专题文档 - 更新 openspec/config.yaml 首读入口和文档影响分析规则 - 修正 docs/prompts/README.md 过时引用和边界说明
This commit is contained in:
101
docs/development/backend.md
Normal file
101
docs/development/backend.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# 后端开发
|
||||
|
||||
本文档说明 my-app 后端的 API、配置加载、日志、版本管理和后端测试开发约定。
|
||||
|
||||
适用场景:修改 src/server/、src/shared/api.ts、后端测试、配置契约、API 响应或日志模块。
|
||||
|
||||
## 库使用优先级
|
||||
|
||||
| 优先级 | 来源 | 典型用途 |
|
||||
| ------ | ------------ | ---------------------------------------- |
|
||||
| 1 | Bun 内置 API | Bun.serve、Bun.file、Bun.YAML、Bun.spawn |
|
||||
| 2 | es-toolkit | 类型判断、深度比较、并发控制 |
|
||||
| 3 | 标准 Web API | Headers、fetch、AbortController |
|
||||
| 4 | 主流三方库 | pino、@sinclair/typebox、ajv |
|
||||
| 5 | 自行实现 | 仅在以上都无法满足时 |
|
||||
|
||||
新增依赖前必须先检查上述每一层是否已有可用方案。
|
||||
|
||||
## API 路由开发
|
||||
|
||||
路由文件位于 src/server/routes/,每个端点一个文件。路由通过 server.ts 的 Bun.serve({ routes }) 声明式注册。
|
||||
|
||||
新增路由步骤:
|
||||
|
||||
1. 在 src/server/routes/ 下创建 <name>.ts
|
||||
2. 实现 handler 函数并 export
|
||||
3. 在 server.ts 的 routes 对象中注册路径和 method handler
|
||||
4. 在 tests/server/ 中添加对应测试
|
||||
|
||||
## 共享工具
|
||||
|
||||
helpers.ts 提供跨路由共用的响应工具:
|
||||
|
||||
- createApiError(error, status) — 构造 API 错误体
|
||||
- createHeaders(mode, init) — 创建响应 Headers
|
||||
- jsonResponse(body, options) — JSON 响应构造
|
||||
|
||||
middleware.ts 提供 API 参数校验函数:
|
||||
|
||||
- validateIdParam(idStr, mode) — 校验 ID 参数格式
|
||||
- validatePagination(pageParam, pageSizeParam, mode) — 校验分页参数
|
||||
- validateTimeRange(from, to, mode) — 校验时间范围参数
|
||||
|
||||
## 类型规范
|
||||
|
||||
- 共享类型以 src/shared/api.ts 为唯一源头
|
||||
- 应用常量以 src/shared/app.ts 为唯一源头
|
||||
- 版本号以 package.json.version 为唯一源头
|
||||
- 前端不得 import src/server/ 下的任何文件
|
||||
- 严格联合类型优先于宽类型
|
||||
|
||||
## 配置契约
|
||||
|
||||
配置加载流程固定为:unknown -> AuthoringConfig -> NormalizedConfig -> ValidatedConfig -> ServerConfig。
|
||||
|
||||
Ajv 保持严格拒绝模式:allErrors: true、不启用类型强制转换、不注入默认值、不自动删除未知字段。
|
||||
|
||||
新增或修改配置字段时必须同步更新 TypeBox schema fragments、config.schema.json、测试和对应用户文档。
|
||||
|
||||
## 日志模块
|
||||
|
||||
后端运行时代码统一通过 Logger 接口输出日志,禁止直接使用 console.\*。
|
||||
|
||||
| 实现 | 用途 |
|
||||
| --------------------- | ------------------------ |
|
||||
| PinoLoggerWrapper | 生产运行时 |
|
||||
| ConsoleFallbackLogger | 配置加载失败前的降级日志 |
|
||||
| NoopLogger | 静默丢弃日志 |
|
||||
| MemoryLogger | 测试替身 |
|
||||
|
||||
敏感信息会自动 redact authorization、cookie、password 等字段。
|
||||
|
||||
## 版本管理
|
||||
|
||||
项目使用 package.json.version 作为版本号唯一来源。
|
||||
|
||||
版本获取方式:
|
||||
|
||||
- 开发模式:src/server/version.ts 运行时从 package.json 读取
|
||||
- 生产模式:scripts/build.ts 在构建时将版本号烘焙为字面量注入
|
||||
|
||||
版本升迁命令:
|
||||
|
||||
```bash
|
||||
bun run version:patch # 升迁 patch 版本
|
||||
bun run version:minor # 升迁 minor 版本
|
||||
bun run version:major # 升迁 major 版本
|
||||
bun run version:set # 显式设置版本号
|
||||
```
|
||||
|
||||
## 后端测试
|
||||
|
||||
| 变更类型 | 测试重点 |
|
||||
| ------------------ | --------------------------------- |
|
||||
| API 路由 | tests/server/app.test.ts 集成行为 |
|
||||
| 配置 schema | schema 导出、合法/非法配置 |
|
||||
| helpers/middleware | 单元测试 |
|
||||
|
||||
## 更新触发条件
|
||||
|
||||
修改后端 API、共享类型、配置契约、日志模块、版本管理或后端测试规范时,必须更新本文档。
|
||||
Reference in New Issue
Block a user