2026-03-11 14:23:11 +08:00

4.5 KiB

Raw Blame History

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

需要验证三类内容：

编译与导入

测试类中的 import、standaloneSetup(...)、构造器引用都更新完成

运行时边界不变

控制器路径不变
鉴权拦截配置不变

文档约定更新

README 中模块结构和 API Boundary Rules 不再要求 controller/internal
示例结构改为 controller + controller/openapi

Risks

类名和文件路径同时重命名，容易遗漏测试 import 或文档引用。
如果存在基于类名扫描或人工 grep 的脚本，需要同步更新引用。
sign 与 file 模块同时涉及包移动，若未同步修改 package 声明会导致编译失败。

Recommendation

先做最小一致性改造：

统一内部控制器类名为 *Controller
去掉 controller/internal 包
更新 README、测试和约定文档

不在这一轮处理：

openapi 控制器风格统一
DTO 包命名统一
额外的模块结构重构

4.5 KiB Raw Blame History Unescape Escape