social-app/docs/plans/2026-02-26-restful-api-refactor-design.md

RESTful API 全面重构设计

日期: 2026-02-26 状态: 待实现

目标

将后端 HTTP API 改造为完全符合 RESTful 规范，并同步更新前端适配代码。

设计原则

1. 资源导向 URL：使用名词而非动词
2. HTTP 语义化：状态通过状态码表达，响应体只包含必要数据
3. 响应格式统一：成功响应无冗余字段，错误响应使用 RFC 7807
4. 文档同步：路由变更必须同步更新文档

URL 重构

Auth 相关

功能	当前 URL	新 URL	HTTP 方法
注册发起	/signup/start	/verifications	POST
重发验证码	/signup/resend	/verifications/resend	POST
验证码校验	/signup/verify	/verifications/verify	POST
登录	/login	/sessions	POST
刷新 Token	/refresh	/sessions/refresh	POST
登出	/logout	/sessions	DELETE
按邮箱查用户	/users/by-email	/users?email=xxx	GET

Profile → Users 统一

功能	当前 URL	新 URL	HTTP 方法
获取个人信息	/profile/me	/users/me	GET
更新个人信息	/profile/me	/users/me	PATCH
按用户名查用户	/profile/{username}	/users/{username}	GET

Agent Chat

功能	当前 URL	新 URL	HTTP 方法
运行对话	/agent-chat/run	/agent-chats	POST

响应格式

成功响应

端点	状态码	响应体
POST /verifications	202	{email: string}
POST /verifications/resend	204	无
POST /verifications/verify	200	{access_token, refresh_token, expires_in, token_type, user}
POST /sessions	200	同上
POST /sessions/refresh	200	同上
DELETE /sessions	204	无
GET /users?email=xxx	200	{id, email, created_at, email_confirmed_at?}
GET /users/me	200	{id, username, avatar_url?, bio?}
PATCH /users/me	200	同上
GET /users/{username}	200	同上
POST /agent-chats	200	{session_id, output, events[]}

错误响应

保持 RFC 7807 格式（已实现）：

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid verification code",
  "instance": "/api/v1/verifications/verify"
}

前端解析优先级：detail → message → error → "请求失败"

Schema 定义

请求 Schema

# verifications
class VerificationCreateRequest(BaseModel):
    username: str = Field(min_length=3, max_length=30)
    email: EmailStr
    password: str = Field(min_length=6)
    redirect_to: str | None = None

class VerificationResendRequest(BaseModel):
    email: EmailStr

class VerificationVerifyRequest(BaseModel):
    email: EmailStr
    token: str = Field(pattern=r"^\d{6}$")

# sessions
class SessionCreateRequest(BaseModel):
    email: EmailStr
    password: str = Field(min_length=6)

class SessionRefreshRequest(BaseModel):
    refresh_token: str = Field(min_length=1)

class SessionDeleteRequest(BaseModel):
    refresh_token: str = Field(min_length=1)

# users
class UserUpdateRequest(BaseModel):
    username: str | None = Field(default=None, min_length=3, max_length=30)
    avatar_url: str | None = None
    bio: str | None = Field(default=None, max_length=200)

响应 Schema

class VerificationCreateResponse(BaseModel):
    email: EmailStr

class SessionResponse(BaseModel):
    access_token: str
    refresh_token: str
    expires_in: int
    token_type: str
    user: AuthUser

class UserResponse(BaseModel):
    id: str
    username: str
    avatar_url: str | None = None
    bio: str | None = None

class UserByEmailResponse(BaseModel):
    id: str
    email: EmailStr
    created_at: str
    email_confirmed_at: str | None = None

文件改动清单

后端

文件	改动
v1/auth/router.py	URL 重命名，简化响应
v1/auth/schemas.py	重命名/简化模型
v1/auth/gateway.py	适配新 schema
v1/auth/service.py	适配新 schema
v1/profile/ → v1/users/	目录重命名
v1/users/router.py	URL 更新
v1/users/schemas.py	重命名模型
v1/agent_chat/router.py	URL 更新
v1/router.py	更新路由注册
测试文件	同步更新

前端

文件	改动
auth/data/auth_api.dart	URL 更新
auth/data/models/auth_response.dart	简化 SignupStartResponse，删除 SignupResendResponse
profile/data/profile_api.dart	改为 users/data/users_api.dart
profile/data/models/profile_response.dart	重命名
相关 cubit/screen	适配新 API

文档

文件	改动
docs/runtime/runtime-route.md	新增，记录所有路由
AGENTS.md	添加路由文档同步规则

风险与缓解

风险	缓解措施
前后端不同步导致功能失效	同时修改，一次性提交
测试覆盖不足	先更新测试，确保通过后再改实现
遗漏某个调用点	全局搜索旧 URL 字符串

验收标准

• 所有后端测试通过
• 所有前端测试通过
• 手动验证注册/登录/登出流程
• runtime-route.md 包含所有端点文档
• AGENTS.md 包含路由同步规则