mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-10-06 23:56:37 +08:00
3.9 KiB
3.9 KiB
提取公共 Response 包以支持 Middleware 统一响应实现计划
1. 目标与背景 (Goal & Context)
- 需求背景:
原本
response.go放在controller目录下。由于middleware处于controller上游,并且和controller跨包,middleware无法直接调用controller的响应逻辑。这导致middleware中存在许多手写的、格式硬编码的c.JSON调用。 如果直接将response.go放入已有的common根包,会引入github.com/gin-gonic/gin依赖,导致依赖common的底层service和model也受到gin框架的依赖污染。 - 开发范围 (Scope):
- 在
openflare_server/common/response下新建response.go子包(package response),存放通用的 HTTP 响应逻辑。 - 将
controller/response.go中的响应逻辑移植到common/response/response.go。 - 在
controller/response.go中保留参数解析逻辑,并作为代理调用common/response中的方法,从而实现对 controller 内 140+ 处现有调用的零改动。 - 修改
middleware包下的所有c.JSON手写响应,统一采用common/response的方法。
- 在
2. 设计与决策 (Design & Decisions)
- 核心对象/数据模型:无需改动任何数据库或数据模型。
- API 与鉴权设计:不改变任何公开 API 接口路由与现有的成功/失败响应 JSON 格式。
- 设计决策权衡:
- 方案 A:直接把 response.go 放入 common 根包
- 缺点:导致原本不应该感知 Web 传输协议的
service、model、job包间接依赖了github.com/gin-gonic/gin框架。
- 缺点:导致原本不应该感知 Web 传输协议的
- 方案 B:在 common 下建子包
common/response- 优点:满足
common归类的直觉,又保持了包的物理依赖隔离。业务底层不受gin污染,而controller和middleware这类传输层可引入该包进行代码复用。(采用此方案)
- 优点:满足
- 方案 A:直接把 response.go 放入 common 根包
3. 具体修改文件清单 (Proposed Changes)
后端 Server
-
[NEW] response.go
- 职责:通用的 Gin 响应工具包,包括
RespondSuccess、RespondSuccessWithExtras、RespondSuccessMessage、RespondFailure、RespondBadRequest、RespondUnauthorized和RespondForbidden。
- 职责:通用的 Gin 响应工具包,包括
-
[MODIFY] response.go
- 职责:删去具体的 HTTP 响应渲染实现,以代理方式调用
common/response包中导出的函数,保持 controller 包内现有调用的向后兼容;保留原有的decodeJSONBody、decodeOptionalJSONBody、parseIDParam、parseIDParamByName、bindJSON参数绑定解析逻辑。
- 职责:删去具体的 HTTP 响应渲染实现,以代理方式调用
-
[MODIFY] agent-auth.go
- 职责:替换
c.JSON(http.StatusUnauthorized, ...)为使用response.RespondUnauthorized(...)渲染统一响应。
- 职责:替换
-
[MODIFY] auth.go
- 职责:替换
c.JSON相关的未授权和失败响应为使用response包方法。
- 职责:替换
-
[MODIFY] jwt.go
- 职责:替换 JWT 未授权的回调响应为使用
response统一格式。
- 职责:替换 JWT 未授权的回调响应为使用
-
[MODIFY] relay-auth.go
- 职责:替换未授权和 StatusForbidden 响应为使用
response方法。
- 职责:替换未授权和 StatusForbidden 响应为使用
-
[MODIFY] tunnel-auth.go
- 职责:替换未授权和 StatusForbidden 响应为使用
response方法。
- 职责:替换未授权和 StatusForbidden 响应为使用
4. 验证计划 (Verification Plan)
自动化单元测试
- 运行项目已有测试验证重构是否影响 API 连通性与响应结构:
go test -v ./router/...go test -v ./service/...