142 lines
8.3 KiB
Markdown
142 lines
8.3 KiB
Markdown
# fire-safety-ymd Go 后端开发规范
|
||
|
||
## 1. 当前技术基线
|
||
|
||
| 项 | 当前选择 | 说明 |
|
||
| --- | --- | --- |
|
||
| Go module | `fire-safety-ymd` | 临时名称，正式仓库路径待确认 |
|
||
| Go 工具链 | 本地 `1.26.6`；Docker builder `1.26.8` | 本地测试已验证；镜像版本已显式固定，目标服务器构建待验证 |
|
||
| HTTP | 标准库 `net/http` | 当前无需 Web 框架 |
|
||
| 测试 | `testing`、`httptest` | 当前无第三方测试库 |
|
||
| 数据库 | PostgreSQL + PostGIS + `pgx/v5 v5.10.0` | 原生 pgxpool、固定只读 SQL；实库 SRID 严格 readiness 已通过 |
|
||
| AI 集成 | SuperAgent Open API Adapter + MCP `2025-06-18` | 协议代码已实现并默认关闭；真实环境待联调 |
|
||
|
||
引入依赖前优先核对官方版本、Go 版本要求、维护状态、许可证和可替代性。核心依赖升级需要独立验证，不能只修改版本号。
|
||
|
||
## 2. 目录职责和依赖方向
|
||
|
||
```text
|
||
cmd/server 进程入口、信号处理、依赖装配
|
||
internal/app 应用生命周期与顶层 wiring
|
||
internal/config 配置读取、默认值和校验
|
||
internal/handler HTTP/MCP 入站契约和响应映射
|
||
internal/service 用例编排、授权后的业务流程
|
||
internal/domain 稳定领域概念、值对象和业务规则
|
||
internal/repository PostgreSQL/PostGIS 等持久化适配
|
||
internal/integration SuperAgent 等外部系统协议适配
|
||
pkg 真正需要对外复用的稳定包
|
||
```
|
||
|
||
依赖原则：
|
||
|
||
- `cmd/server` 只装配，不承载业务逻辑。
|
||
- Handler 不直接执行 SQL，不直接依赖 SuperAgent 厂商 DTO。
|
||
- Service 通过小接口使用持久化或外部系统；接口优先定义在使用方附近。
|
||
- Domain 不依赖 HTTP、数据库驱动、MCP SDK 或 SuperAgent SDK。
|
||
- Repository 负责参数化查询、行映射和数据库错误转换，不组织自然语言回答。
|
||
- 避免为了分层而创建一一映射的空结构；只有出现真实职责时才增加文件和抽象。
|
||
|
||
## 3. 包与 API 设计
|
||
|
||
- 包名短、小写、表达单一能力，不使用 `utils`、`common`、`base` 等无边界集合。
|
||
- 导出标识符必须有稳定的外部使用场景；默认保持在 `internal` 或不导出。
|
||
- 接口应小，由调用方定义；不要先为每个结构体创建接口。
|
||
- 构造函数显式传入必需依赖，依赖缺失应尽早失败。
|
||
- 避免包级可变状态、隐式 `init` 副作用和 service locator。
|
||
- `context.Context` 作为有取消、超时或请求范围操作的第一个参数，不保存在长期结构体字段中。
|
||
- 时间使用 `time.Time`/`time.Duration`；跨系统时间格式、时区和精度必须在契约中明确。
|
||
|
||
## 4. 错误处理
|
||
|
||
- 正常业务失败返回错误，不使用 `panic`。
|
||
- 使用 `fmt.Errorf("动作和对象: %w", err)` 添加上下文并保留错误链。
|
||
- 用 `errors.Is`/`errors.As` 判断语义，不比较错误文本。
|
||
- Domain/Service 错误映射为稳定 API code；客户端不依赖中英文 message 做逻辑判断。
|
||
- HTTP 响应和日志不回显 SQL、凭证、Token、完整个人信息或第三方原始敏感响应。
|
||
- 不静默吞掉影响正确性的错误；确实只能忽略时要有注释或受控观测方式。
|
||
|
||
## 5. HTTP 规范
|
||
|
||
- 路由显式声明方法；不支持的方法返回 405。
|
||
- JSON 响应设置 `Content-Type: application/json; charset=utf-8`。
|
||
- Handler 只做协议解析、格式校验、可信身份上下文读取、调用 Service 和响应映射。
|
||
- 请求体设置合理大小上限；服务端设置 Header、请求、空闲和优雅关闭超时。
|
||
- 后续统一错误格式、请求 ID 和日志关联字段，并在 Spec/OpenAPI 中形成唯一契约来源。
|
||
- `/health` 当前是 liveness，只说明进程可处理 HTTP；依赖就绪检查应使用独立 readiness 端点，不能改变现有语义而不更新契约。
|
||
|
||
## 6. 配置与 Secret
|
||
|
||
- 环境变量名称使用项目明确前缀，例如 `FIRE_SAFETY_`。
|
||
- 配置由 `internal/config` 一次读取、校验并作为不可变值注入。
|
||
- Secret 不设置可误用的生产默认值，不写入仓库、命令参数、普通日志或错误响应。
|
||
- 本地 `.env` 被忽略；需要示例时只提交无真实值且有注释的 `.env.example`。
|
||
- 启动时验证必需配置，错误指出配置键但不输出其值。
|
||
|
||
## 7. PostgreSQL/PostGIS 规范
|
||
|
||
数据库接入遵守：
|
||
|
||
- 当前使用 `pgx/v5` 原生 `pgxpool`；升级前核对 Go/PostgreSQL 支持范围、安全变更和回归测试。
|
||
- 所有值使用参数绑定，表名和排序字段使用代码白名单；绝不拼接模型生成 SQL。
|
||
- 使用最小权限数据库角色，MCP 第一阶段默认为只读。
|
||
- 查询设置请求超时和数据库 statement timeout；分页、数量上限和空间半径必须有限制。
|
||
- 事务边界由 Service 用例决定，Repository 不隐藏跨用例事务。
|
||
- 已发布 migration 只追加，不原地篡改；导入原始 SQL 前单独审计 `DROP`、sequence、owner 和 extension 依赖。
|
||
- `geometry` 的 SRID、实际类型和有效性先通过真实数据核验，再决定字段约束与查询。
|
||
- 经纬度距离计算明确选择合适的 `geography`、投影转换或测地算法，并以米等业务单位返回。
|
||
- 用 `ST_DWithin` 等可利用 GiST 索引的条件限制候选集，避免对整表逐行计算距离。
|
||
- WKB、GeoJSON、经纬度和 MultiLineString/Polygon 映射必须有代表性测试。
|
||
|
||
## 8. SuperAgent 与 MCP 适配
|
||
|
||
- 外部 SDK 和 DTO 只存在于适配层；Service 使用项目自己的端口和领域对象。
|
||
- 当前 SuperAgent Adapter 分离 `CreateSession` 与 `StreamMessage`；上层负责持久化本地会话映射，不能每轮隐式创建新 Session。
|
||
- SSE 成功必须同时具备最终内容、成功 `run.completed` 和顶层 `end`；断流只恢复既有 Run，不重新 POST 消息。
|
||
- DashScope 风格兼容 Handler 只做入站协议转换，与原生 `/api/chat` 共享 Chat Service；兼容 `session_id` 必须映射本地会话，不能直接暴露或接受 Provider Session。
|
||
- 兼容 SSE v1 不透传 `message.delta`；只有严格成功后才以 `finish_reason=stop` 返回正文。若要真正逐字输出，必须先更新 Spec、安全失败语义和客户端验收条件。
|
||
- 当前 MCP 只实现 `2025-06-18` 的 initialize、initialized notification、tools/list、tools/call 和同步 JSON 响应；扩展 SSE、session 或新协议版本前需更新 Spec。
|
||
- 重试只用于可安全重试的操作，并设置次数、退避和总时限；避免重复创建会话或重复业务动作。
|
||
- MCP 工具按领域能力命名，输入输出 schema 稳定、有限且有中文业务说明。
|
||
- `user_id`、角色、租户/区域等授权上下文由服务端注入，不成为模型可自由选择的普通参数。
|
||
- 工具结果保留结构化状态、来源和不确定性，不让 Agent 解析日志或数据库原始字段。
|
||
|
||
## 9. 测试与验证
|
||
|
||
基础命令：
|
||
|
||
```bash
|
||
gofmt -w ./cmd ./internal
|
||
go test ./...
|
||
```
|
||
|
||
按风险增加：
|
||
|
||
```bash
|
||
go vet ./...
|
||
go test -race ./...
|
||
```
|
||
|
||
测试要求：
|
||
|
||
- 纯逻辑优先使用表驱动单元测试。
|
||
- HTTP 使用 `httptest` 验证方法、状态码、Header、JSON 和错误边界。
|
||
- Repository 集成测试使用隔离数据库和可重复迁移，不依赖个人长期数据库。
|
||
- PostGIS 测试覆盖 SRID、点/线/面、边界点、空几何、无效几何、半径上限和排序稳定性。
|
||
- 外部适配测试覆盖超时、取消、断流、限流、鉴权失败和不完整事件。
|
||
- 测试夹具不得包含真实联系人、Token、生产坐标或客户数据。
|
||
|
||
## 10. 日志与可观测性
|
||
|
||
- 使用结构化日志字段表达 request、tool、duration、result 和 error category，避免拼接大段原始内容。
|
||
- 不记录 Authorization、Cookie、数据库 DSN、完整用户问题中的敏感信息或完整 MCP 结果。
|
||
- 后续为 HTTP、SuperAgent、MCP 和数据库调用建立统一 request/correlation ID。
|
||
- 指标区分业务无结果、权限拒绝、上游失败、超时和内部错误，不能只看 HTTP 500 总数。
|
||
|
||
## 11. 提交前检查
|
||
|
||
- 仅包含本 checkpoint 文件，没有覆盖用户已有变更。
|
||
- `gofmt` 和相关测试已运行。
|
||
- 新依赖有理由且 `go.mod`/`go.sum` 一致。
|
||
- 没有 Secret、真实敏感数据、构建产物或 IDE 文件。
|
||
- Project State、接口、安全和相关设计文档已同步。
|