feat: 更新路由参数约定,要求数字ID路径参数在@Router注解中显式声明类型以确保正确匹配

This commit is contained in:
2025-12-29 15:44:25 +08:00
parent 9d598e7f9b
commit bdf20fb0c6

View File

@@ -30,7 +30,7 @@ This file condenses `backend/docs/dev/http_api.md` + `backend/docs/dev/model.md`
- DO NOT manually write route declarations (only `atomctl gen route`).
- DO keep Swagger annotations consistent with actual Fiber route paths (including `:param`).
- MUST: route path parameter placeholders MUST be `camelCase` (e.g. `:tenantCode`), never `snake_case` (e.g. `:tenant_code`).
- MUST: for numeric ID path params (`int/int64` like `tenantID/userID/orderID`), prefer Fiber typed params `:tenantID<int>` to avoid conflicts with static subpaths (e.g. `/orders/statistics`) and reduce ambiguous routing.
- MUST: for numeric ID path params (`int/int64` like `tenantID/userID/orderID/id`), explicit declaration `:param<int>` is REQUIRED in `@Router` annotation to ensure proper route matching and constraints (e.g. `@Router /v1/users/:id<int> [get]`).
- MUST: when importing another HTTP module's `dto` package, the import alias MUST be `<module>_dto` (e.g. `tenant_dto`), not `<module>dto` (e.g. `tenantdto`).
- MUST: when creating/generating Go `struct` definitions (DTOs/requests/responses/etc.), add detailed per-field comments describing meaning, usage scenario, and validation/usage rules (do not rely on “self-explanatory” names).
- MUST: business code comments MUST be written in Chinese (中文注释), to keep review/maintenance consistent across the team.
@@ -250,7 +250,7 @@ In this case:
- `backend/app/events/subscribers/<snake_case>.go`subscriber实现 `contracts.EventHandler`,负责 `Topic()` + `Handler(...)`
- 生成后:按项目约定运行一次 `atomctl gen provider`(用于刷新 DI/provider 生成文件)。
### Topic约定
### Topic 约定
- 统一在 `backend/app/events/topics.go` 维护 topic 常量,避免散落在各处形成“字符串协议”。
- topic 字符串建议使用稳定前缀(例如 `event:`),并使用 `snake_case` 命名。
@@ -299,7 +299,7 @@ Common types:
- `Kind` 建议与业务枚举/事件类型对齐,便于 SQL/报表按 `kind` 过滤。
- `Data` 写入对应 payload 的 JSONpayload 可以是多个不同 struct
- 读取时:
- 先 `snap := model.Snapshot.Data()`,再 `switch snap.Kind` 选择对应 payload结构去 `json.Unmarshal(snap.Data, &payload)`。
- 先 `snap := model.Snapshot.Data()`,再 `switch snap.Kind` 选择对应 payload 结构去 `json.Unmarshal(snap.Data, &payload)`。
- 兼容历史数据(旧 JSON 没有 kind/data`UnmarshalJSON` 可以将其标记为 `legacy` 并把原始 JSON 放入 `Data`,避免线上存量读取失败。
---
@@ -464,4 +464,4 @@ func (s *XxxTestSuite) Test_Method() {
So(got, ShouldBeNil)
})
}
```
```