2026-08-04 18:59:21 +08:00
|
|
|
|
# 后端目录与模块边界
|
|
|
|
|
|
|
|
|
|
|
|
## 当前布局
|
|
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
|
zhixing-server/
|
|
|
|
|
|
├── src/zhixing_server/
|
|
|
|
|
|
│ ├── bootstrap/ # 应用工厂和进程配置
|
|
|
|
|
|
│ │ ├── app.py
|
|
|
|
|
|
│ │ └── config.py
|
|
|
|
|
|
│ ├── interfaces/http/ # 跨上下文 HTTP 路由目录
|
|
|
|
|
|
│ │ ├── router.py # /api/v1 路由目录
|
|
|
|
|
|
│ │ └── system.py # /healthz、/api/v1/system/status
|
|
|
|
|
|
│ ├── modules/ # 业务 bounded context（目前为空）
|
|
|
|
|
|
│ │ └── README.md
|
|
|
|
|
|
│ ├── shared/ # 没有特定业务所有权的小型基础能力
|
|
|
|
|
|
│ ├── main.py # ASGI 入口，只导出 app
|
|
|
|
|
|
│ └── __init__.py
|
|
|
|
|
|
└── tests/ # 按行为/入口组织的 pytest 测试
|
2026-08-04 16:47:58 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
2026-08-04 18:59:21 +08:00
|
|
|
|
`zhixing-server/src/zhixing_server/bootstrap/app.py:create_app` 负责组合 FastAPI 应用，`main.py` 只执行 `app = create_app()`。不要把应用组合、环境读取或业务逻辑塞进 `main.py`。
|
2026-08-04 16:47:58 +08:00
|
|
|
|
|
2026-08-04 18:59:21 +08:00
|
|
|
|
## 新增业务上下文
|
2026-08-04 16:47:58 +08:00
|
|
|
|
|
2026-08-04 18:59:21 +08:00
|
|
|
|
只有在领域语言和所有权边界明确后，才在 `modules/` 下创建上下文。推荐形状来自 `zhixing-server/src/zhixing_server/modules/README.md`：
|
2026-08-04 16:47:58 +08:00
|
|
|
|
|
2026-08-04 18:59:21 +08:00
|
|
|
|
```text
|
|
|
|
|
|
modules/<bounded_context>/
|
|
|
|
|
|
├── domain/ # 实体、值对象、领域服务、端口
|
|
|
|
|
|
├── application/ # 用例和编排
|
|
|
|
|
|
├── infrastructure/ # 存储及外部系统适配器
|
|
|
|
|
|
└── presentation/ # HTTP 或消息驱动的交付适配器
|
|
|
|
|
|
```
|
2026-08-04 16:47:58 +08:00
|
|
|
|
|
2026-08-04 18:59:21 +08:00
|
|
|
|
domain 层不能导入 FastAPI、持久化客户端或 infrastructure 适配器。上下文内的 presentation 负责把输入转换成用例需要的类型；顶层 `interfaces/http` 只承载跨上下文的运维入口和路由目录。
|
2026-08-04 16:47:58 +08:00
|
|
|
|
|
2026-08-04 18:59:21 +08:00
|
|
|
|
## 命名与导入
|
2026-08-04 16:47:58 +08:00
|
|
|
|
|
2026-08-04 18:59:21 +08:00
|
|
|
|
- Python 包、模块和函数使用 `snake_case`；测试文件使用 `test_*.py`，例如 `tests/test_system_http.py`。
|
|
|
|
|
|
- 对外公开的类、响应模型和函数应有类型标注与文档字符串，参照 `bootstrap/config.py` 和 `interfaces/http/system.py`。
|
|
|
|
|
|
- `shared/` 只能放跨上下文且无业务归属的原语；不要把某个上下文的领域规则放进去。
|
|
|
|
|
|
- 避免新建全局 `services/`、`repositories/` 或 `utils/` 目录来绕过上下文边界。
|
2026-08-04 16:47:58 +08:00
|
|
|
|
|
2026-08-04 18:59:21 +08:00
|
|
|
|
## 参考实现
|
2026-08-04 16:47:58 +08:00
|
|
|
|
|
2026-08-04 18:59:21 +08:00
|
|
|
|
- 应用组合：`zhixing-server/src/zhixing_server/bootstrap/app.py`
|
|
|
|
|
|
- 路由目录：`zhixing-server/src/zhixing_server/interfaces/http/router.py`
|
|
|
|
|
|
- 运维/系统端点：`zhixing-server/src/zhixing_server/interfaces/http/system.py`
|
|
|
|
|
|
- 当前 HTTP 契约测试：`zhixing-server/tests/test_system_http.py`
|
