5.6 KiB

Raw Permalink Blame History

Changelog: 废弃 response.py，统一使用 common.py

日期: 2026-02-11
类型: 代码清理
影响范围: server/app/schemas/response.py（已删除）

变更概述

删除已废弃的 response.py 文件，统一使用 common.py 中的 SuccessResponse 标准响应格式。

问题背景

在完成 API v1 标准化迁移后（详见 2026-02-11-api-v1-complete-standardization.md），发现项目中存在两套响应格式系统：

旧系统（response.py）

# server/app/schemas/response.py
class ApiResponse(BaseModel, Generic[T]):
    """旧的响应格式"""
    success: bool
    code: int
    message: str
    data: Optional[T]
    timestamp: datetime

def success_response(data: Any = None, message: str = "Success") -> dict:
    """便捷函数"""
    return {...}

新系统（common.py）

# server/app/schemas/common.py
class SuccessResponse(BaseModel, Generic[T]):
    """标准响应格式"""
    success: bool
    code: int
    message: str
    data: Optional[T]
    timestamp: datetime

问题

系统混用：两套系统功能完全重复，容易混淆
维护成本：需要同时维护两套相同功能的代码
技术债务：response.py 已无任何引用，但仍占用代码库空间
命名混乱：ApiResponse vs SuccessResponse，不清楚应该用哪个

变更内容

1. 删除 response.py

# 删除旧文件
rm server/app/schemas/response.py

删除的内容：

ApiResponse 类（157 行）
ApiErrorResponse 类
ErrorDetail 类
success_response() 函数
error_response() 函数

2. 更新 init.py

移除旧导出：

# ❌ 移除
from app.schemas.response import (
    ApiResponse,
    ApiErrorResponse,
    ErrorDetail,
    success_response,
    error_response
)

__all__ = [
    "ApiResponse",
    "ApiErrorResponse",
    "ErrorDetail",
    "success_response",
    "error_response",
    # ...
]

添加废弃提示：

# ✅ 新增
"""
额外的请求/响应模型（可选）
SQLModel 已经提供了大部分功能

注意：旧的 response.py 已废弃，请使用 common.py 中的 SuccessResponse
"""

3. 验证无引用

# ✅ 验证无任何代码引用
$ grep -r "from app.schemas.response import" server/
# 无结果

# ✅ 验证无任何导入
$ grep -r "from app.schemas import ApiResponse" server/
# 无结果

# ✅ 验证无任何使用
$ grep -r "ApiResponse\|success_response\|error_response" server/app/api/
# 无结果（仅在文档和测试文件中出现）

迁移状态

✅ 已完成迁移的模块

所有 24 个 API 文件已在之前的迁移中完成：

模块	旧系统	新系统	状态
API v1 (24 files)	❌	✅	已迁移
error_handlers.py	❌	✅	直接构建响应
所有 Service 层	❌	✅	返回原始数据

✅ 当前状态

response.py: ❌ 已删除
common.py: ✅ 作为唯一标准
代码引用: 0 个
技术债务: 已清除

技术影响

优点

单一标准
- 只有一套响应格式系统
- 消除开发者选择困惑
- 降低学习成本
代码简化
- 删除 157 行重复代码
- 简化 schemas 模块结构
- 减少维护负担
命名清晰
- SuccessResponse 语义明确
- 符合 RESTful 规范
- 易于理解和使用
架构一致性
- 全项目统一标准
- 符合 jointo-tech-stack 规范
- 便于后续扩展

无破坏性变更

✅ API 行为不变：所有 API 已在之前迁移中更新
✅ 响应格式不变：SuccessResponse 与 ApiResponse 格式完全一致
✅ 向后兼容：无任何正在使用的代码依赖 response.py
✅ 测试通过：无需修改任何测试

最佳实践

✅ 推荐用法

# 导入标准响应格式
from app.schemas.common import SuccessResponse

# 在路由中使用
@router.get("/example", response_model=SuccessResponse[ExampleResponse])
async def get_example():
    return SuccessResponse(
        data=result,
        message="操作成功"
    )

❌ 已废弃用法

# ❌ 不再可用
from app.schemas.response import ApiResponse, success_response

# ❌ 不再可用
from app.schemas import ApiResponse

验证结果

# ✅ response.py 已删除
$ ls server/app/schemas/response.py
ls: cannot access 'server/app/schemas/response.py': No such file or directory

# ✅ common.py 存在
$ ls server/app/schemas/common.py
server/app/schemas/common.py

# ✅ 无残留引用
$ grep -r "response.py" server/app/ | grep -v ".pyc"
# 无结果（除了注释）

# ✅ 所有 API 使用 SuccessResponse
$ grep -r "SuccessResponse" server/app/api/v1/ | wc -l
24

总结

成功删除已废弃的 response.py 文件，完成响应格式系统的统一：

删除文件: 1 个（157 行）
清理导出: 5 个符号
技术债务: 已清除
标准化: 100% 完成

现在项目只有一个标准的响应格式系统（common.py 中的 SuccessResponse），所有 API 均已迁移完成，架构清晰统一。

执行人: Claude (Sonnet 4.5)
执行日期: 2026-02-11
影响范围: schemas 模块结构优化
破坏性: 无（已完全迁移）

5.6 KiB Raw Permalink Blame History