tcjlj/OpenFlare
1
0
Fork 0
mirror of https://github.com/Rain-kl/OpenFlare.git synced 2026-09-29 05:56:38 +08:00
Code Issues Packages Projects Releases Wiki Activity

[优化] response 结构调整

Browse Source
This commit is contained in:
ryan
2026-06-05 11:32:10 +08:00
parent a5257be319
commit 4dc4c745c8
9 changed files with 164 additions and 96 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/changelog/index.md
+2
View File
@@ -26,6 +26,8 @@ sidebar: false
### 变更
- 提取并新增 `common/response` 通用响应子包，替换 `controller/response.go` 中的响应细节，重构所有中间件中硬编码的 `c.JSON` 响应，统一 API 响应格式并隔离 Gin 依赖。
- 将 `usage.md` 改名为 `proxy-config.md`（新建反代配置），重新梳理大纲结构，专注于如何从导入/申请证书开始，一步步新增并发布代理路由规则，并同步更新全部导航与文档引用链接
- WAF 白名单调整为准入名单语义：存在白名单规则时，未命中白名单的请求会被拦截
- 更新仓库结构设计文档，使 `openflare_agent` 和 `openflare_server` 的目录结构描述与实际物理结构保持一致
docs/plan/20260605-move-response-to-common.md
+53
View File
@@ -0,0 +1,53 @@
# 提取公共 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` 框架。
* **方案 B：在 common 下建子包 `common/response`**
* 优点：满足 `common` 归类的直觉，又保持了包的物理依赖隔离。业务底层不受 `gin` 污染，而 `controller` 和 `middleware` 这类传输层可引入该包进行代码复用。**（采用此方案）**
## 3. 具体修改文件清单 (Proposed Changes)
### 后端 Server
* #### [NEW] [response.go](file:///Users/ryan/DEV/Go/OpenFlare/openflare_server/common/response/response.go)
* 职责：通用的 Gin 响应工具包，包括 `RespondSuccess`、`RespondSuccessWithExtras`、`RespondSuccessMessage`、`RespondFailure`、`RespondBadRequest`、`RespondUnauthorized` 和 `RespondForbidden`。
* #### [MODIFY] [response.go](file:///Users/ryan/DEV/Go/OpenFlare/openflare_server/controller/response.go)
* 职责：删去具体的 HTTP 响应渲染实现，以代理方式调用 `common/response` 包中导出的函数，保持 controller 包内现有调用的向后兼容；保留原有的 `decodeJSONBody`、`decodeOptionalJSONBody`、`parseIDParam`、`parseIDParamByName`、`bindJSON` 参数绑定解析逻辑。
* #### [MODIFY] [agent-auth.go](file:///Users/ryan/DEV/Go/OpenFlare/openflare_server/middleware/agent-auth.go)
* 职责：替换 `c.JSON(http.StatusUnauthorized, ...)` 为使用 `response.RespondUnauthorized(...)` 渲染统一响应。
* #### [MODIFY] [auth.go](file:///Users/ryan/DEV/Go/OpenFlare/openflare_server/middleware/auth.go)
* 职责：替换 `c.JSON` 相关的未授权和失败响应为使用 `response` 包方法。
* #### [MODIFY] [jwt.go](file:///Users/ryan/DEV/Go/OpenFlare/openflare_server/middleware/jwt.go)
* 职责：替换 JWT 未授权的回调响应为使用 `response` 统一格式。
* #### [MODIFY] [relay-auth.go](file:///Users/ryan/DEV/Go/OpenFlare/openflare_server/middleware/relay-auth.go)
* 职责：替换未授权和 StatusForbidden 响应为使用 `response` 方法。
* #### [MODIFY] [tunnel-auth.go](file:///Users/ryan/DEV/Go/OpenFlare/openflare_server/middleware/tunnel-auth.go)
* 职责：替换未授权和 StatusForbidden 响应为使用 `response` 方法。
---
## 4. 验证计划 (Verification Plan)
### 自动化单元测试
* 运行项目已有测试验证重构是否影响 API 连通性与响应结构：
```bash
go test -v ./router/...
```
```bash
go test -v ./service/...
```
openflare_server/common/response/response.go
+82
View File
@@ -0,0 +1,82 @@
package response
import (
"net/http"
"github.com/gin-gonic/gin"
)
const invalidParamsMessage = "参数错误"
// RespondSuccess sends a successful response with data
func RespondSuccess(c *gin.Context, data any) {
c.JSON(http.StatusOK, gin.H{
"success": true,
"message": "",
"data": data,
})
}
// RespondSuccessWithExtras sends a successful response with data and extra fields
func RespondSuccessWithExtras(c *gin.Context, data any, extras gin.H) {
payload := gin.H{
"success": true,
"message": "",
"data": data,
}
for key, value := range extras {
payload[key] = value
}
c.JSON(http.StatusOK, payload)
}
// RespondSuccessMessage sends a successful response with a custom message
func RespondSuccessMessage(c *gin.Context, message string) {
c.JSON(http.StatusOK, gin.H{
"success": true,
"message": message,
})
}
// RespondFailure sends a failed response with http.StatusOK and a failure message
func RespondFailure(c *gin.Context, message string) {
c.JSON(http.StatusOK, gin.H{
"success": false,
"message": message,
})
}
// RespondBadRequest sends a bad request response (400)
func RespondBadRequest(c *gin.Context, message string) {
if message == "" {
message = invalidParamsMessage
}
c.JSON(http.StatusBadRequest, gin.H{
"success": false,
"message": message,
})
}
// RespondUnauthorized sends an unauthorized response (401)
func RespondUnauthorized(c *gin.Context, message string) {
c.JSON(http.StatusUnauthorized, gin.H{
"success": false,
"message": message,
})
}
// RespondForbidden sends a forbidden response (403)
func RespondForbidden(c *gin.Context, message string) {
c.JSON(http.StatusForbidden, gin.H{
"success": false,
"message": message,
})
}
// RespondErrorWithStatus sends a response with target HTTP status code and a message
func RespondErrorWithStatus(c *gin.Context, code int, message string) {
c.JSON(code, gin.H{
"success": false,
"message": message,
})
}
openflare_server/controller/response.go
+8 -36
View File
@@ -4,63 +4,35 @@ import (
"encoding/json"
"errors"
"io"
"net/http"
"strconv"
"github.com/gin-gonic/gin"
"openflare/common/response"
)
const invalidParamsMessage = "参数错误"
func respondSuccess(c *gin.Context, data any) {
c.JSON(http.StatusOK, gin.H{
"success": true,
"message": "",
"data": data,
})
response.RespondSuccess(c, data)
}
func respondSuccessWithExtras(c *gin.Context, data any, extras gin.H) {
payload := gin.H{
"success": true,
"message": "",
"data": data,
}
for key, value := range extras {
payload[key] = value
}
c.JSON(http.StatusOK, payload)
response.RespondSuccessWithExtras(c, data, extras)
}
func respondSuccessMessage(c *gin.Context, message string) {
c.JSON(http.StatusOK, gin.H{
"success": true,
"message": message,
})
response.RespondSuccessMessage(c, message)
}
func respondFailure(c *gin.Context, message string) {
c.JSON(http.StatusOK, gin.H{
"success": false,
"message": message,
})
response.RespondFailure(c, message)
}
func respondBadRequest(c *gin.Context, message string) {
if message == "" {
message = invalidParamsMessage
}
c.JSON(http.StatusBadRequest, gin.H{
"success": false,
"message": message,
})
response.RespondBadRequest(c, message)
}
func respondUnauthorized(c *gin.Context, message string) {
c.JSON(http.StatusUnauthorized, gin.H{
"success": false,
"message": message,
})
response.RespondUnauthorized(c, message)
}
func decodeJSONBody(body io.Reader, target any) error {
openflare_server/middleware/agent-auth.go
+3 -9
View File
@@ -2,7 +2,7 @@ package middleware
import (
"github.com/gin-gonic/gin"
"net/http"
"openflare/common/response"
"openflare/service"
)
@@ -11,10 +11,7 @@ func AgentAuth() func(c *gin.Context) {
token := c.GetHeader("X-Agent-Token")
node, err := service.AuthenticateAccessToken(token)
if err != nil {
c.JSON(http.StatusUnauthorized, gin.H{
"success": false,
"message": "无权进行此操作，Agent Token 无效",
})
response.RespondUnauthorized(c, "无权进行此操作，Agent Token 无效")
c.Abort()
return
}
@@ -32,10 +29,7 @@ func AgentRegisterAuth() func(c *gin.Context) {
return
}
if err := service.ValidateDiscoveryToken(token); err != nil {
c.JSON(http.StatusUnauthorized, gin.H{
"success": false,
"message": "无权进行此操作，注册 Token 无效",
})
response.RespondUnauthorized(c, "无权进行此操作，注册 Token 无效")
c.Abort()
return
}
openflare_server/middleware/auth.go
+8 -29
View File
@@ -1,8 +1,8 @@
package middleware
import (
"net/http"
"openflare/common"
"openflare/common/response"
"openflare/model"
jwt "github.com/appleboy/gin-jwt/v2"
@@ -14,20 +14,14 @@ const OpenFlareTokenHeader = "OpenFlare-Token"
func authHelper(c *gin.Context, minRole int) {
tokenStr := c.GetHeader(OpenFlareTokenHeader)
if tokenStr == "" {
c.JSON(http.StatusUnauthorized, gin.H{
"success": false,
"message": "无权进行此操作，未登录或 token 无效",
})
response.RespondUnauthorized(c, "无权进行此操作，未登录或 token 无效")
c.Abort()
return
}
token, err := JWTMiddleware.ParseTokenString(tokenStr)
if err != nil {
c.JSON(http.StatusUnauthorized, gin.H{
"success": false,
"message": "无权进行此操作，token 无效: " + err.Error(),
})
response.RespondUnauthorized(c, "无权进行此操作，token 无效: "+err.Error())
c.Abort()
return
}
@@ -35,10 +29,7 @@ func authHelper(c *gin.Context, minRole int) {
claims := jwt.ExtractClaimsFromToken(token)
id, ok := claims["id"].(float64)
if !ok {
c.JSON(http.StatusUnauthorized, gin.H{
"success": false,
"message": "无权进行此操作，token 格式错误",
})
response.RespondUnauthorized(c, "无权进行此操作，token 格式错误")
c.Abort()
return
}
@@ -47,37 +38,25 @@ func authHelper(c *gin.Context, minRole int) {
dbErr := model.DB.Select([]string{"id", "username", "display_name", "role", "status", "token"}).
First(dbUser, "id = ?", int(id)).Error
if dbErr != nil || dbUser.Username == "" {
c.JSON(http.StatusUnauthorized, gin.H{
"success": false,
"message": "无权进行此操作，用户不存在",
})
response.RespondUnauthorized(c, "无权进行此操作，用户不存在")
c.Abort()
return
}
if dbUser.Token != tokenStr {
c.JSON(http.StatusUnauthorized, gin.H{
"success": false,
"message": "无权进行此操作，token 已失效或已登出",
})
response.RespondUnauthorized(c, "无权进行此操作，token 已失效或已登出")
c.Abort()
return
}
if dbUser.Status == common.UserStatusDisabled {
c.JSON(http.StatusOK, gin.H{
"success": false,
"message": "用户已被封禁",
})
response.RespondFailure(c, "用户已被封禁")
c.Abort()
return
}
if int(dbUser.Role) < minRole {
c.JSON(http.StatusOK, gin.H{
"success": false,
"message": "无权进行此操作，权限不足",
})
response.RespondFailure(c, "无权进行此操作，权限不足")
c.Abort()
return
}
openflare_server/middleware/jwt.go
+2 -4
View File
@@ -3,6 +3,7 @@ package middleware
import (
"log"
"openflare/common"
"openflare/common/response"
"openflare/model"
"time"
@@ -57,10 +58,7 @@ func InitJWTMiddleware() {
return data != nil
},
Unauthorized: func(c *gin.Context, code int, message string) {
c.JSON(code, gin.H{
"success": false,
"message": "无权进行此操作，未登录或 token 无效: " + message,
})
response.RespondErrorWithStatus(c, code, "无权进行此操作，未登录或 token 无效: "+message)
},
TokenLookup: "header: OpenFlare-Token",
TokenHeadName: "", // Empty for raw token value directly
openflare_server/middleware/relay-auth.go
+3 -9
View File
@@ -2,7 +2,7 @@ package middleware
import (
"github.com/gin-gonic/gin"
"net/http"
"openflare/common/response"
"openflare/service"
)
@@ -13,18 +13,12 @@ func RelayAuth() func(c *gin.Context) {
token := c.GetHeader("X-Agent-Token")
node, err := service.AuthenticateAccessToken(token)
if err != nil {
c.JSON(http.StatusUnauthorized, gin.H{
"success": false,
"message": "无权进行此操作，Agent Token 无效",
})
response.RespondUnauthorized(c, "无权进行此操作，Agent Token 无效")
c.Abort()
return
}
if node.NodeType != "tunnel_relay" {
c.JSON(http.StatusForbidden, gin.H{
"success": false,
"message": "此节点不是 TunnelRelay 类型",
})
response.RespondForbidden(c, "此节点不是 TunnelRelay 类型")
c.Abort()
return
}
openflare_server/middleware/tunnel-auth.go
+3 -9
View File
@@ -1,7 +1,7 @@
package middleware
import (
"net/http"
"openflare/common/response"
"openflare/service"
"github.com/gin-gonic/gin"
@@ -15,18 +15,12 @@ func TunnelAuth() func(c *gin.Context) {
token := c.GetHeader("X-Tunnel-Token")
node, err := service.AuthenticateAccessToken(token)
if err != nil {
c.JSON(http.StatusUnauthorized, gin.H{
"success": false,
"message": "无权进行此操作，Tunnel Token 无效",
})
response.RespondUnauthorized(c, "无权进行此操作，Tunnel Token 无效")
c.Abort()
return
}
if node.NodeType != "tunnel_client" {
c.JSON(http.StatusForbidden, gin.H{
"success": false,
"message": "此节点不是 TunnelClient 类型",
})
response.RespondForbidden(c, "此节点不是 TunnelClient 类型")
c.Abort()
return
}