部分重构
This commit is contained in:
+246
@@ -0,0 +1,246 @@
|
||||
# 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
|
||||
**更新内容**：重构路由和中间件系统，引入分层架构和兼容性支持
|
||||
Reference in New Issue
Block a user