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:
2026-04-15 11:29:20 +08:00
parent e8990f7771
commit 913a235e5c
2 changed files with 50 additions and 5 deletions

View File

@@ -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 上手动执行迁移