docs: 更新 AGENTS.md 和 IMPROVEMENTS.md,记录已知兼容性问题
AGENTS.md: - 添加已知兼容性问题章节 - actix-ratelimit 0.3.1 与 actix-web 4.x 不兼容 - actix-web-prom 与当前架构不兼容 - 添加路由配置结构说明(App 配置顺序、middleware 应用方式) - 添加路由优先级说明 IMPROVEMENTS.md: - 2.1 缺少请求频率限制:标记 ⚠️,记录兼容性问题及备选方案 - 6.1 缺少性能指标收集:标记 ⚠️,记录兼容性问题及备选方案 - 修正无日志聚合的 checkbox 状态
This commit is contained in:
37
AGENTS.md
37
AGENTS.md
@@ -152,6 +152,17 @@ FREE_USER_DATA_LIMIT=20
|
||||
|
||||
## 约束条件
|
||||
|
||||
### 已知兼容性问题
|
||||
⚠️ **actix-ratelimit 0.3.1 与 actix-web 4.x 不兼容**
|
||||
- 错误:`Transform<ResourceService>` trait bound 不满足
|
||||
- 原因:该 crate 基于 actix-web 3.x 设计
|
||||
- 备选:actix-web-lab、手动 HashMap 实现、Nginx 层限流
|
||||
|
||||
⚠️ **actix-web-prom 与当前架构不兼容**
|
||||
- 错误:`ServiceFactory Response` 类型冲突(expected `ServiceResponse`, found `ServiceResponse<EitherBody<..., ...>>`)
|
||||
- 原因:middleware 改变了 App 返回类型,与 `impl Trait` 返回类型冲突
|
||||
- 备选:actix-web-lab、手动 atomic 计数器、Nginx access log
|
||||
|
||||
### 禁止事项
|
||||
- 在 JWT Claims 中添加 `is_admin`(必须查询数据库)
|
||||
- 信任 JWT 中的 `is_paid` 来做配额决策(必须查询数据库)
|
||||
@@ -175,6 +186,32 @@ FREE_USER_DATA_LIMIT=20
|
||||
3. 在 `create_server_config` 中注册(如果是受保护接口,放在 JWT 作用域内)
|
||||
4. 如需要,在 `models.rs` 中添加请求/响应结构体
|
||||
|
||||
### 路由配置结构
|
||||
```rust
|
||||
// create_server_config 函数中的 App 配置顺序很重要
|
||||
App::new()
|
||||
.app_data(web::Data::new(pool)) // 数据源
|
||||
.app_data(web::Data::new(http_client))
|
||||
.app_data(web::Data::new(app_state))
|
||||
// 公开接口(无 middleware)
|
||||
.service(login) // POST /api/login
|
||||
.service(get_weather_details) // GET /api/weather/details
|
||||
// 受保护接口(JWT middleware)
|
||||
.service(
|
||||
web::scope("")
|
||||
.wrap(from_fn(jwt_middleware)) // JWT 验证
|
||||
.service(post_weather_data) // POST /api/post-weather-data
|
||||
// ... 其他受保护接口
|
||||
)
|
||||
// 静态文件和健康检查放最后
|
||||
.service(web::resource("/static/{tail:.*}").route(web::get().to(serve_static_files)))
|
||||
.service(health_check)
|
||||
```
|
||||
|
||||
### 路由优先级
|
||||
- `web::scope("/")` 内的路由路径不带前缀(handlers 已有 `#[post("/api/...")]` 等属性)
|
||||
- 公开接口和受保护接口分开,便于添加不同的 middleware
|
||||
|
||||
### 修改数据库
|
||||
1. 在 `migrations/` 中创建迁移 SQL
|
||||
2. 在 PostgreSQL 上手动执行迁移
|
||||
|
||||
Reference in New Issue
Block a user