136 lines
4.5 KiB
Markdown
136 lines
4.5 KiB
Markdown
# Controller Internal Convention Removal Design
|
||
|
||
**Date:** 2026-03-11
|
||
|
||
## Goal
|
||
|
||
去掉“非 openapi 接口必须使用 `controller/internal` 包和 `*InternalController` 命名”的项目约定，将内部业务接口控制器统一收敛到中性 `controller` 包和 `*Controller` 类名，同时保持现有 URL、鉴权和 Swagger 暴露行为完全不变。
|
||
|
||
## Scope
|
||
|
||
本设计覆盖：
|
||
- `controller/internal` -> `controller` 的包路径调整
|
||
- `*InternalController` -> `*Controller` 的类名调整
|
||
- 测试引用、README、结构说明、命名约定同步更新
|
||
|
||
本设计不覆盖：
|
||
- `/api/**` 与 `/openapi/**` 路径变更
|
||
- DTO 包结构调整
|
||
- 鉴权规则变更
|
||
- `openapi` 控制器命名风格调整
|
||
- service/repository 结构重构
|
||
|
||
## Current State
|
||
|
||
当前仓库对内部接口有一套强命名约定：
|
||
- 内部业务接口通常命名为 `*InternalController`
|
||
- 其中部分模块控制器位于 `controller/internal`
|
||
- README 明确规定：`Internal API controllers only in */controller/internal`
|
||
|
||
实际代码状态并不统一：
|
||
- `auth`、`device`、`init`、`system` 使用 `controller` 包，但类名仍为 `*InternalController`
|
||
- `file` 使用 `controller/internal` 包，类名为 `FileInternalController`
|
||
- `sign` 模块同时存在 `controller/internal` 和 `controller/openapi`
|
||
|
||
这意味着“internal controller”已经被项目文档和部分代码固化，但在包结构上并未完全一致。
|
||
|
||
## Design Choice
|
||
|
||
采用：`统一改为 controller + *Controller`
|
||
|
||
不采用：`只改文档，不改代码`
|
||
|
||
原因：
|
||
- 用户目标是去掉该设定本身，而不是仅仅弱化描述
|
||
- 如果只改文档，现有类名和包名仍然持续强化旧约定
|
||
|
||
不采用：`只改类名，不改包路径`
|
||
|
||
原因：
|
||
- `controller/internal` 目录仍会继续表达旧分层含义
|
||
- 无法真正完成约定清理
|
||
|
||
不采用：`新增一套中性 Controller，保留旧类做代理`
|
||
|
||
原因：
|
||
- 没有兼容性收益
|
||
- 会引入重复 Bean 或重复请求映射风险
|
||
|
||
## Naming Rule After Change
|
||
|
||
调整后的规则：
|
||
- `/api/**` 控制器放在 `modules/*/controller`
|
||
- `/openapi/**` 控制器继续放在 `modules/*/controller/openapi`
|
||
- 内部控制器类名使用中性 `*Controller`
|
||
- 对外接口控制器命名不强制带 `Open` 前缀，但当前已有 `OpenSignController` 可暂时保留
|
||
|
||
## Class Rename Plan
|
||
|
||
建议重命名如下：
|
||
- `AuthInternalController` -> `AuthController`
|
||
- `DeviceInternalController` -> `DeviceController`
|
||
- `CryptoCardInternalController` -> `CryptoCardController`
|
||
- `InitInternalController` -> `InitController`
|
||
- `HealthInternalController` -> `HealthController`
|
||
- `InternalSignController` -> `SignController`
|
||
- `FileInternalController` -> `FileController`
|
||
|
||
对应包路径调整：
|
||
- `modules/file/controller/internal` -> `modules/file/controller`
|
||
- `modules/sign/controller/internal` -> `modules/sign/controller`
|
||
|
||
其余当前已在 `controller` 包下的类，仅改类名即可。
|
||
|
||
## Compatibility Boundary
|
||
|
||
以下内容必须保持不变：
|
||
- `@RequestMapping` 路径
|
||
- 所有 `/api/v1/**` 路径
|
||
- 所有 `/openapi/**` 路径
|
||
- `WebMvcConfig` 的拦截规则
|
||
- Swagger/OpenAPI 文档访问路径
|
||
- 前端、脚本、curl 示例调用路径
|
||
|
||
也就是说，这次是纯 Java 命名与项目约定调整，不是 API 行为调整。
|
||
|
||
## Security Impact
|
||
|
||
鉴权策略不变：
|
||
- `/api/**` 继续走内部 token 拦截器
|
||
- `/openapi/**` 继续走 openapi 签名拦截器
|
||
|
||
因为拦截器是基于 URL 前缀，而不是控制器类名或包名，所以控制器重命名不会影响运行时鉴权行为。
|
||
|
||
## Testing Strategy
|
||
|
||
需要验证三类内容：
|
||
|
||
1. 编译与导入
|
||
- 测试类中的 import、`standaloneSetup(...)`、构造器引用都更新完成
|
||
|
||
2. 运行时边界不变
|
||
- 控制器路径不变
|
||
- 鉴权拦截配置不变
|
||
|
||
3. 文档约定更新
|
||
- README 中模块结构和 API Boundary Rules 不再要求 `controller/internal`
|
||
- 示例结构改为 `controller + controller/openapi`
|
||
|
||
## Risks
|
||
|
||
1. 类名和文件路径同时重命名，容易遗漏测试 import 或文档引用。
|
||
2. 如果存在基于类名扫描或人工 grep 的脚本，需要同步更新引用。
|
||
3. `sign` 与 `file` 模块同时涉及包移动，若未同步修改 package 声明会导致编译失败。
|
||
|
||
## Recommendation
|
||
|
||
先做最小一致性改造：
|
||
- 统一内部控制器类名为 `*Controller`
|
||
- 去掉 `controller/internal` 包
|
||
- 更新 README、测试和约定文档
|
||
|
||
不在这一轮处理：
|
||
- `openapi` 控制器风格统一
|
||
- DTO 包命名统一
|
||
- 额外的模块结构重构
|