246 lines
6.0 KiB
Markdown
246 lines
6.0 KiB
Markdown
# 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. 中间件加载顺序
|
||
|
||
```go
|
||
// 在 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/*）
|
||
|
||
```go
|
||
// 在 routers/ 中的原有路由文件
|
||
- apiUsers.go # 用户认证和管理
|
||
- apiFiles.go # 文件上传和管理
|
||
- apiPurchase.go # 采购订单管理
|
||
- apiStatic.go # 静态文件服务
|
||
```
|
||
|
||
### RESTful API v1（/api/v1/*）
|
||
|
||
```go
|
||
// 在 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`
|
||
|
||
### 配置位置
|
||
|
||
```go
|
||
// 在 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`
|
||
```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/"
|
||
# ... 其他配置
|
||
```
|
||
|
||
## 快速启动
|
||
|
||
### 开发环境
|
||
```bash
|
||
# Windows
|
||
run-dev.bat
|
||
|
||
# 手动运行
|
||
set CGO_ENABLED=1
|
||
go run ./cmd/ops-server/main.go
|
||
```
|
||
|
||
### 生产构建
|
||
```bash
|
||
# 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
|
||
**更新内容**：重构路由和中间件系统，引入分层架构和兼容性支持 |