mirror of
https://github.com/RaisFast/raisfast.git
synced 2026-09-24 00:02:28 +00:00
361 lines
10 KiB
Markdown
361 lines
10 KiB
Markdown
# 改进计划
|
||
|
||
> 基于项目审计，按优先级列出待修复和改进项。
|
||
|
||
## P0 — 关键问题（影响正确性/安全）
|
||
|
||
### 1. 特定限流器完全失效
|
||
|
||
**文件：** `src/middleware/rate_limit.rs`
|
||
|
||
**问题：** `rate_limit_fn!` 宏在每次请求中创建新的 `RateLimiter` 实例（空 HashMap），导致登录（10次/分）、注册（5次/时）、评论（3次/分）的限流永远不触发。仅全局限流器（通过 `Extension` 共享）有效。
|
||
|
||
**修复方案：** 将特定限流器也放入 `AppState`，或通过 `Extension` 共享多个命名限流器实例。
|
||
|
||
```rust
|
||
// 方案 A：AppState 中持有多个限流器
|
||
pub struct AppState {
|
||
pub pool: SqlitePool,
|
||
pub config: Arc<AppConfig>,
|
||
pub rate_limiters: RateLimiterSet,
|
||
}
|
||
|
||
pub struct RateLimiterSet {
|
||
pub global: RateLimiter,
|
||
pub register: RateLimiter,
|
||
pub login: RateLimiter,
|
||
pub comment: RateLimiter,
|
||
}
|
||
```
|
||
|
||
**验收标准：** 连续发送 11 次登录请求，第 11 次应返回 429。
|
||
|
||
---
|
||
|
||
### 2. N+1 查询
|
||
|
||
**文件：** `src/services/post.rs` — `build_post_response()`
|
||
|
||
**问题：** 文章列表每篇文章执行 3 次额外查询（tags、author_name、category_name），N 篇文章共 3N+1 次查询。
|
||
|
||
**修复方案：** 改用 JOIN 一次查询，或批量查询后 HashMap 映射。
|
||
|
||
```sql
|
||
-- 方案 A：JOIN 查询
|
||
SELECT p.*, c.name AS category_name, u.username AS author_name
|
||
FROM posts p
|
||
LEFT JOIN categories c ON p.category_id = c.id
|
||
LEFT JOIN users u ON p.author_id = u.id
|
||
WHERE p.status = 'published'
|
||
ORDER BY p.created_at DESC
|
||
LIMIT ? OFFSET ?;
|
||
|
||
-- tags 批量查询
|
||
SELECT pt.post_id, t.id, t.name, t.slug
|
||
FROM posts_tags pt
|
||
JOIN tags t ON pt.tag_id = t.id
|
||
WHERE pt.post_id IN (...);
|
||
```
|
||
|
||
**验收标准：** `list_posts` 查询次数从 3N+1 降至 2~3 次。
|
||
|
||
---
|
||
|
||
### 3. 密码验证不完整
|
||
|
||
**文件：** `src/models/user.rs` — `RegisterRequest`
|
||
|
||
**问题：** 仅校验长度 ≥ 8，未检查必须包含字母和数字。`aaaaaaaa` 可通过验证。
|
||
|
||
**修复方案：** 增加 `validate` 自定义函数，或使用 `validator` 的 `regex` / `custom` 校验。
|
||
|
||
```rust
|
||
#[derive(Debug, Deserialize, Validate)]
|
||
pub struct RegisterRequest {
|
||
#[validate(email)]
|
||
pub email: String,
|
||
#[validate(length(min = 2, max = 50))]
|
||
pub username: String,
|
||
#[validate(length(min = 8, max = 128), custom(function = "validate_password"))]
|
||
pub password: String,
|
||
}
|
||
|
||
fn validate_password(pwd: &str) -> Result<(), validator::ValidationError> {
|
||
let has_letter = pwd.chars().any(|c| c.is_ascii_alphabetic());
|
||
let has_digit = pwd.chars().any(|c| c.is_ascii_digit());
|
||
if has_letter && has_digit {
|
||
Ok(())
|
||
} else {
|
||
Err(ValidationError::new("password_strength"))
|
||
}
|
||
}
|
||
```
|
||
|
||
**验收标准：** `aaaaaaaa`、`12345678` 被拒绝，`abc12345` 通过。
|
||
|
||
---
|
||
|
||
### 4. 全局请求体大小限制缺失
|
||
|
||
**文件：** `src/server/mod.rs`
|
||
|
||
**问题：** 仅 `/media/upload` 有 `RequestBodyLimitLayer`，其他 POST 端点无限制。恶意请求可发送超大 JSON body。
|
||
|
||
**修复方案：** 在 `api_v1` 路由组外层添加默认限制，upload 路由使用更大的限制。
|
||
|
||
```rust
|
||
let api_v1 = axum::Router::new()
|
||
// ... 所有路由 ...
|
||
.layer(RequestBodyLimitLayer::new(2 * 1024 * 1024)) // 全局 2MB
|
||
.layer(from_fn(global_rate_limit))
|
||
.layer(Extension(RateLimiter::new(...)));
|
||
```
|
||
|
||
upload 路由单独覆盖为 5MB：
|
||
|
||
```rust
|
||
.route("/media/upload", http_post(media::upload)
|
||
.layer(RequestBodyLimitLayer::new(5 * 1024 * 1024)))
|
||
```
|
||
|
||
**验收标准：** 发送 >2MB 的 JSON 到任意 POST 端点返回 413。
|
||
|
||
---
|
||
|
||
## P1 — 高优先级（影响功能/规范符合度）
|
||
|
||
### 5. CSRF 防护
|
||
|
||
**问题：** 无 CSRF token 生成和校验。规范 `guide.md` 6.3 要求实现。
|
||
|
||
**修复方案：** 使用 `axum-csrf` 或手动实现 Double Submit Cookie 模式。
|
||
|
||
由于 API 使用 Bearer Token（非 Cookie），CSRF 风险较低。若前端改为 Cookie 认证则必须实现。
|
||
|
||
**优先级评估：** 当前 Bearer Token 方案下可降为 P2。若未来改用 Cookie 认证则必须立即实现。
|
||
|
||
---
|
||
|
||
### 6. 代码语法高亮
|
||
|
||
**问题：** Markdown 渲染（`comrak`）未配置语法高亮。规范 `guide.md` 5.1 要求使用 `syntect`。
|
||
|
||
**修复方案：** 添加 `syntect` 依赖，在 `render_markdown` 中集成。
|
||
|
||
```rust
|
||
// src/utils/markdown.rs
|
||
use syntect::highlighting::ThemeSet;
|
||
use syntect::html::highlighted_html_for_string;
|
||
use syntect::parsing::SyntaxSet;
|
||
|
||
pub fn render_markdown(input: &str) -> String {
|
||
// comrak 渲染 markdown → HTML
|
||
// 对 <code> 块使用 syntect 高亮
|
||
}
|
||
```
|
||
|
||
**注意：** `syntect` 增加约 10MB 编译体积和启动时语法集加载时间。可考虑在构建时预生成 HTML。
|
||
|
||
---
|
||
|
||
### 7. SQL 编译时校验
|
||
|
||
**问题：** 所有 SQL 查询使用 `sqlx::query()` / `sqlx::query_as()`（运行时检查），未使用 `sqlx::query!` / `sqlx::query_as!`（编译时校验）。
|
||
|
||
**修复方案：** 启用 `sqlx` 的 `offline` feature，运行 `cargo sqlx prepare` 生成查询元数据，逐步迁移为宏形式。
|
||
|
||
```toml
|
||
# Cargo.toml
|
||
sqlx = { version = "0.8", features = ["runtime-tokio", "sqlite", "offline"] }
|
||
```
|
||
|
||
**迁移优先级：** 从 `models/` 层开始（SQL 最集中），`services/` 层次之。
|
||
|
||
**注意：** 这是一项大规模重构，建议分批进行，每批一个 model 文件。
|
||
|
||
---
|
||
|
||
### 8. 评论列表分页
|
||
|
||
**文件：** `src/models/comment.rs` — `find_approved_by_post()`
|
||
|
||
**问题：** 一次查询文章所有已审核评论，无分页。热门文章评论数可达数千条。
|
||
|
||
**修复方案：** 增加分页参数，前端支持懒加载/无限滚动。
|
||
|
||
```rust
|
||
pub async fn find_approved_by_post_paginated(
|
||
pool: &SqlitePool,
|
||
post_id: &str,
|
||
page: i64,
|
||
page_size: i64,
|
||
) -> AppResult<(Vec<Comment>, i64)> {
|
||
let offset = (page - 1) * page_size;
|
||
// 查询 + COUNT
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## P2 — 中优先级（影响可扩展性/代码质量）
|
||
|
||
### 9. 限流器内存无限增长
|
||
|
||
**文件：** `src/middleware/rate_limit.rs`
|
||
|
||
**问题：** 清理仅在 `check()` 调用时触发。低流量时过期条目长期驻留内存。
|
||
|
||
**修复方案：** 添加后台定时清理任务。
|
||
|
||
```rust
|
||
// server 启动时 spawn 一个清理任务
|
||
tokio::spawn(async move {
|
||
let mut interval = tokio::time::interval(Duration::from_secs(300));
|
||
loop {
|
||
interval.tick().await;
|
||
limiter.cleanup_expired().await;
|
||
}
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
### 10. `#[non_exhaustive]` 缺失
|
||
|
||
**问题：** 公开 API 类型（`AppError`、`ApiResponse`、请求/响应结构体）缺少 `#[non_exhaustive]`，无法安全地添加字段/变体而不破坏向后兼容。
|
||
|
||
**修复方案：** 为所有公开类型添加 `#[non_exhaustive]`。
|
||
|
||
```rust
|
||
#[non_exhaustive]
|
||
pub enum AppError {
|
||
BadRequest(String),
|
||
Unauthorized,
|
||
Forbidden,
|
||
NotFound(String),
|
||
Conflict(String),
|
||
Internal(String),
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 11. sync_tags 批量插入
|
||
|
||
**文件：** `src/services/post.rs` — `sync_tags()`
|
||
|
||
**问题：** 逐条 INSERT + DELETE，N 个标签需要 N 次数据库操作。
|
||
|
||
**修复方案：** 使用事务 + 批量操作。
|
||
|
||
```rust
|
||
pub async fn sync_tags(pool: &SqlitePool, post_id: &str, tag_ids: &[String]) -> AppResult<()> {
|
||
let mut tx = pool.begin().await?;
|
||
sqlx::query("DELETE FROM posts_tags WHERE post_id = ?")
|
||
.bind(post_id)
|
||
.execute(&mut *tx)
|
||
.await?;
|
||
for tag_id in tag_ids {
|
||
sqlx::query("INSERT INTO posts_tags (post_id, tag_id) VALUES (?, ?)")
|
||
.bind(post_id)
|
||
.bind(tag_id)
|
||
.execute(&mut *tx)
|
||
.await?;
|
||
}
|
||
tx.commit().await?;
|
||
Ok(())
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 12. 限流器水平扩展
|
||
|
||
**问题：** 内存存储，多实例部署时限流状态不共享。
|
||
|
||
**修复方案：** 抽象 `RateLimitStore` trait，提供 `MemoryStore`（当前）和 `RedisStore`（未来）实现。
|
||
|
||
```rust
|
||
#[async_trait]
|
||
pub trait RateLimitStore: Send + Sync {
|
||
async fn increment(&self, key: &str, window_secs: u64) -> u64;
|
||
async fn get(&self, key: &str) -> u64;
|
||
}
|
||
```
|
||
|
||
当部署为多实例时，切换为 Redis 后端即可。
|
||
|
||
---
|
||
|
||
### 13. update_role 使用类型化请求
|
||
|
||
**文件：** `src/handlers/user.rs` — `update_role()`
|
||
|
||
**问题：** 手动解析 `serde_json::Value`，绕过了 `validator` 校验。
|
||
|
||
**修复方案：** 定义带验证的请求结构体。
|
||
|
||
```rust
|
||
#[derive(Debug, Deserialize, Validate)]
|
||
pub struct UpdateRoleRequest {
|
||
#[validate(length(min = 1))]
|
||
pub role: String,
|
||
}
|
||
|
||
pub async fn update_role(
|
||
_admin: AdminUser,
|
||
State(state): State<crate::AppState>,
|
||
Path(id): Path<String>,
|
||
Json(req): Json<UpdateRoleRequest>,
|
||
) -> AppResult<ApiResponse<UserResponse>> {
|
||
if !["reader", "author", "admin"].contains(&req.role.as_str()) {
|
||
return Err(AppError::BadRequest("invalid role".into()));
|
||
}
|
||
// ...
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## P3 — 低优先级（锦上添花）
|
||
|
||
### 14. 单元测试 & 测试基础设施
|
||
|
||
**当前状态：** 60 个集成测试通过，但无单元测试、无 mock、无快照测试、无基准测试。`rstest` 已引入但未使用。
|
||
|
||
**改进项：**
|
||
- 为 `services/` 层添加单元测试（使用 `mockall` 隔离数据库）
|
||
- 为 `utils/markdown.rs` 添加快照测试（`insta`）
|
||
- 为热点路径（文章列表、JWT 验证）添加基准测试（`criterion`）
|
||
- CI 中使用 `cargo nextest` 替代 `cargo test`
|
||
|
||
### 15. 错误日志级别调整
|
||
|
||
**问题：** `BadRequest`、`NotFound` 等客户端错误记录为 `ERROR` 级别。
|
||
|
||
**修复：** 4xx 错误用 `tracing::warn!`，5xx 才用 `tracing::error!`。
|
||
|
||
### 16. view_count 并发安全
|
||
|
||
**文件：** `src/services/post.rs` — `get_post()`
|
||
|
||
**问题：** `find_published_by_slug` 和 `increment_view_count` 不是原子操作。高并发下可能出现计数偏差。
|
||
|
||
**修复方案：** 使用 SQL 单条语句 `UPDATE posts SET view_count = view_count + 1 WHERE slug = ? RETURNING *`，或在查询后用原子计数器。
|
||
|
||
### 17. 静态文件目录
|
||
|
||
**问题：** 规范中的 `static/` 目录未创建。
|
||
|
||
**修复：** 创建 `static/` 目录，用于 favicon、robots.txt 等静态资源，通过 `ServeDir` 挂载。
|
||
|
||
---
|
||
|
||
## 实施建议
|
||
|
||
按以下顺序分批推进：
|
||
|
||
1. **第一批（1-2 天）：** P0 全部 — #1 限流器、#2 N+1、#3 密码验证、#4 请求体限制
|
||
2. **第二批（2-3 天）：** P1 — #8 评论分页、#13 类型化请求、#5 CSRF 评估
|
||
3. **第三批（持续）：** P2/P3 — #6 语法高亮、#7 SQL 编译时校验、#9-12 扩展性改进、#14 测试
|