ops2/DOC/路由和中间件配置.md

OPS 系统路由和中间件配置文档

概览

本文档描述了OPS系统的路由架构和中间件配置，这些配置已经在2026-03-31完成更新。

路由架构

1. 路由层次结构

/api                     # 兼容性API层（保持原有接口）
  ├─ /users              # 用户认证和管理（兼容现有前端）
  ├─ /files              # 文件上传和管理
  ├─ /purchase           # 采购订单管理
  └─ /static             # 静态文件服务

/api/v1                  # RESTful API v1（新架构）
  ├─ /users              # 用户API（新架构）
  ├─ /files              # 文件API（新架构）
  └─ /purchase           # 采购API（新架构）

/                        # 前端静态文件

2. 主路由配置文件

backend/
├── api/
│   ├── main.go          # 主路由配置入口
│   └── v1/
│       └── routes.go    # v1 API路由定义
├── cmd/ops-server/
│   └── main.go          # 应用程序主入口
└── routers/             # 兼容性路由（旧架构）

中间件配置

1. 中间件加载顺序

// 在 cmd/ops-server/main.go 中
r := gin.New()

// 1. CORS中间件
r.Use(middleware.CORS())

// 2. 日志中间件（环境相关）
if isDevelopment {
    r.Use(middleware.SimpleLogger())  // 开发环境：简易日志
} else {
    r.Use(middleware.Logger(logger))   // 生产环境：详细日志
}

// 3. 恢复中间件
r.Use(middleware.Recovery(logger))

2. 可用的中间件

middleware.CORS()

• 支持完整的CORS头配置
• 允许跨域请求，支持凭证
• 兼容现有前端系统

middleware.Logger()

• 详细的HTTP请求日志
• 包含请求ID、响应时间、客户端IP等信息
• 敏感信息过滤（如密码）

middleware.SimpleLogger()

• 开发环境使用的简易日志
• 控制台输出格式化的日志信息
• 便于开发和调试

middleware.Recovery()

• Panic恢复中间件
• 捕获并记录Panic信息
• 返回适当的500错误响应

middleware.AuthToken()

• 认证令牌中间件
• 支持多种认证方式：
  1. Authorization: Bearer <token>
  2. POST数据中的 userCookieValue 字段
  3. Cookie头中的 userCookieValue
  4. URL查询参数中的 userCookieValue

middleware.AuthRequired()

• 需要认证的中间件
• 如果用户未认证，返回401错误
• 调用 AuthToken() 中间件并检查结果

API路由配置

兼容性路由（/api/*）

// 在 routers/ 中的原有路由文件
- apiUsers.go       # 用户认证和管理
- apiFiles.go       # 文件上传和管理
- apiPurchase.go    # 采购订单管理
- apiStatic.go      # 静态文件服务

RESTful API v1（/api/v1/*）

// 在 api/v1/routes.go 中
func RegisterRoutes(r *gin.RouterGroup) {
    // 用户认证路由
    userGroup := r.Group("/users")
    {
        userGroup.POST("/login", authHandler.UserLogin)
        userGroup.POST("/register", authHandler.UserRegister)
        userGroup.POST("/logout", middleware.AuthRequired(), authHandler.UserLogout)
    }
    
    // 文件管理路由
    fileGroup := r.Group("/files")
    {
        fileGroup.POST("/upload", middleware.AuthRequired(), fileHandler.UploadFile)
        fileGroup.GET("/list", middleware.AuthRequired(), fileHandler.GetFileList)
    }
    
    // 采购订单路由
    purchaseGroup := r.Group("/purchase")
    {
        purchaseGroup.GET("/orders", middleware.AuthRequired(), purchaseHandler.GetOrders)
        purchaseGroup.POST("/orders", middleware.AuthRequired(), purchaseHandler.CreateOrder)
    }
}

静态文件服务

静态文件处理策略

1. API请求优先：所有以 /api 开头的请求由API路由处理
2. 静态文件服务：其他请求尝试从 ./dist 目录提供静态文件
3. SPA支持：对于Vue Router的history模式，没有匹配的文件时会返回 index.html

配置位置

// 在 api/main.go 中的 NoRoute 处理
r.NoRoute(func(c *gin.Context) {
    if strings.HasPrefix(path, "/api") {
        // API 404错误
        c.JSON(404, ...)
    } else {
        // 静态文件服务
        fs.ServeHTTP(c.Writer, c.Request)
    }
})

开发和生产环境配置

开发环境

• 调试模式日志
• 简易的日志输出
• 本地主机（127.0.0.1:8080）

生产环境

• 生产模式日志
• 详细的JSON日志
• 优化的服务器配置
• TLS支持（如果配置）

关键配置文件

backend/data/config.yaml

web:
  host: "127.0.0.1"
  port: "8080"
  tls: false
  certPrivatePath: ""
  certPublicPath: ""

database:
  type: "sqlite"
  path: "data/database.db"

user:
  cookieTimeout: 604800
  passHashType: "md5"

file:
  maxSize: 52428800
  paths:
    avatar: "data/static/avatar/"
    image: "data/upload/image/"
    # ... 其他配置

快速启动

开发环境

# Windows
run-dev.bat

# 手动运行
set CGO_ENABLED=1
go run ./cmd/ops-server/main.go

生产构建

# Linux/macOS（需要CGO）
CGO_ENABLED=1 GOOS=linux GOARCH=amd64 go build -o ops-server ./cmd/ops-server

# Windows（需要CGO）
set CGO_ENABLED=1
go build -o ops-server.exe ./cmd/ops-server

升级和迁移说明

1. 新架构完全兼容现有前端API
2. 新增 /api/v1 RESTful API用于新功能开发
3. 中间件系统已统一，支持环境感知配置
4. 静态文件服务更智能，支持SPA应用

故障排除

常见问题

1. SQLite需要CGO：设置 CGO_ENABLED=1 环境变量
2. 端口占用：检查端口8080是否被占用，可在config.yaml中修改
3. 静态文件404：确保前端已构建，文件位于 ./dist 目录
4. 数据库连接失败：检查SQLite文件路径和权限

日志级别

• 开发环境：控制台输出，易于阅读
• 生产环境：JSON格式，便于日志收集和分析

---

最后更新：2026-03-31 更新内容：重构路由和中间件系统，引入分层架构和兼容性支持