wdh-home
8164eec650
Some checks failed
CI / init (push) Has been cancelled
CI / Frontend node 18.16.0 (push) Has been cancelled
CI / Backend go (1.22) (push) Has been cancelled
CI / devops-test (1.22, 18.16.0) (push) Has been cancelled
CI / release-pr (push) Has been cancelled
CI / release-please (push) Has been cancelled
CI / devops-prod (1.22, 18.x) (push) Has been cancelled
CI / docker (push) Has been cancelled
43 lines
2.1 KiB
Markdown
43 lines
2.1 KiB
Markdown
# 同模块 admin/app 接口分层规范
|
||
|
||
## 适用范围
|
||
|
||
- 同一业务模块同时存在 `admin` 管理端接口和 `app` 用户端接口时，使用本文。
|
||
|
||
## 强制规则
|
||
|
||
- 顶层目录一律按业务模块落点；禁止因为有 `app` 端，就单独新建顶层 `router/app`、`api/v1/app`、`service/app`、`model/app` 来承载 `book`、`order`、`author` 这类业务。
|
||
- 同一业务模块的实体仍统一放在 `model/<module>`；只有接口入参、出参和流程按 `admin` / `app` 分开。
|
||
- `router/<module>`、`api/v1/<module>`、`service/<module>` 内，`admin` 与 `app` 接口必须分文件或分承载结构体；禁止长期混写在同一个大文件里。
|
||
- 可复用逻辑优先下沉到 `service/<module>` 的公共方法；公共逻辑只抽业务共性，不要把 `admin` / `app` 的鉴权、返回、分页口径硬揉成一套。
|
||
|
||
## 推荐落点
|
||
|
||
- 推荐文件名：`<module>_admin.go`、`<module>_app.go`、`enter.go`。
|
||
- 示例：
|
||
- `router/book/book_admin.go`
|
||
- `router/book/book_app.go`
|
||
- `api/v1/book/book_admin.go`
|
||
- `api/v1/book/book_app.go`
|
||
- `service/book/book_admin.go`
|
||
- `service/book/book_app.go`
|
||
- `service/book/book_common.go`
|
||
- `model/book/book.go`
|
||
- `model/book/request/book_admin.go`
|
||
- `model/book/request/book_app.go`
|
||
- `model/book/response/book_admin.go`
|
||
- `model/book/response/book_app.go`
|
||
|
||
## 路由与鉴权
|
||
|
||
- `admin` 接口默认挂业务 router 的 `PrivateGroup`，走后台 `JWT + Casbin`。
|
||
- `app` 公开接口挂 `PublicGroup`。
|
||
- `app` 仅登录接口，基于 `PublicGroup` 单独加 `middleware.JWTAuth()`；不要直接挂 `PrivateGroup`。
|
||
- 如果 `app` 用户体系不等于 `sys_users`，禁止直接复用后台登录、claims、角色权限链路；必须单独实现用户端认证链路。
|
||
|
||
## 禁止事项
|
||
|
||
- 禁止把“同一业务模块的 app 端接口”误建成独立业务模块。
|
||
- 禁止为了省事，把所有 `app` 接口都挂到 `PrivateGroup`，再用后台角色权限去模拟用户端登录态。
|
||
- 禁止同一个业务实体在 `model` 层拆出两套重复表结构，仅因接口面向 `admin` / `app` 不同。
|