docs/v1.0/server/README.md

服务器文档索引

欢迎查看 Jointo API 服务器文档。

📚 文档列表

错误处理相关

1. 错误处理优化说明

   • 优化目标和安全性提升
   • 优化前后对比
   • 错误类型映射表
   • 使用建议和最佳实践

2. 错误响应对比

   • 详细的优化前后对比示例
   • 各种场景的错误响应
   • 前端集成示例
   • 环境配置建议

3. 错误处理器重构说明

   • 重构目标和动机
   • 代码行数对比
   • 重构步骤详解
   • 最佳实践和后续优化建议

4. 错误处理架构说明

   • 完整的架构设计
   • 模块职责划分
   • 错误处理流程图
   • 安全特性和扩展指南

🎯 快速导航

我想了解...

"为什么要优化错误处理？"

→ 查看 错误处理优化说明

"优化前后有什么区别？"

→ 查看 错误响应对比

"如何进行代码重构？"

→ 查看 错误处理器重构说明

"完整的架构设计是怎样的？"

→ 查看 错误处理架构说明

📁 相关代码文件

核心模块

• app/core/error_handlers.py - 错误处理核心模块
• app/main.py - 应用入口（已优化）
• app/schemas/response.py - 响应格式定义

测试文件

• tests/unit/test_error_handlers.py - 单元测试
• tests/test_error_handling.py - 集成测试示例
• tests/integration/test_project_api.py - 项目 API 测试

🔑 核心改进

1. 安全性提升 🔒

• ✅ 隐藏技术实现细节
• ✅ 不暴露框架版本
• ✅ 环境隔离（开发/生产）

2. 用户体验改善 😊

• ✅ 友好的错误提示
• ✅ 清晰的字段定位
• ✅ 提供修复建议

3. 代码质量提升 💎

• ✅ 模块化设计
• ✅ 单一职责
• ✅ 易于测试和维护

4. 开发效率提升 🚀

• ✅ 一行代码注册所有处理器
• ✅ 统一的错误响应格式
• ✅ 开发环境详细日志

📊 重构成果

main.py 行数: 238 → 107 (-55%)
新增模块: core/error_handlers.py (250 行)
测试覆盖: 30+ 测试用例
文档页面: 4 个详细文档

🎓 学习路径

初学者

1. 阅读 错误处理优化说明
2. 查看 错误响应对比 中的示例
3. 尝试修改 ERROR_TYPE_MESSAGES 添加自定义错误

中级开发者

1. 学习 错误处理器重构说明
2. 阅读 app/core/error_handlers.py 源码
3. 编写单元测试验证理解

高级开发者

1. 深入研究 错误处理架构说明
2. 扩展自定义异常处理器
3. 优化性能和国际化支持

🛠️ 常见任务

添加新的错误类型

# 1. 在 error_handlers.py 中添加映射
ERROR_TYPE_MESSAGES = {
    # ... 现有映射 ...
    "my_custom_error": "自定义错误消息"
}

# 2. 如有特殊逻辑，在 get_friendly_error_message 中处理
if error_type == "my_custom_error":
    return f"特殊处理: {ctx.get('detail')}"

添加自定义异常处理器

# 1. 定义异常处理器
async def my_exception_handler(request: Request, exc: MyException):
    return create_error_response(
        status_code=400,
        message=str(exc)
    )

# 2. 在 register_exception_handlers 中注册
def register_exception_handlers(app):
    # ... 现有注册 ...
    app.add_exception_handler(MyException, my_exception_handler)

编写测试

# tests/unit/test_error_handlers.py
def test_my_error_message():
    error = {"type": "my_custom_error", "ctx": {...}}
    message = get_friendly_error_message(error)
    assert "expected content" in message

📞 支持

如有问题或建议，请：

1. 查看相关文档
2. 检查测试用例
3. 查看源码注释
4. 向团队咨询

🔄 版本历史

v2.0 (2026-02-05)

• ✅ 重构错误处理逻辑
• ✅ 抽离 core/error_handlers.py 模块
• ✅ 优化安全性和用户体验
• ✅ 完善文档和测试

v1.0 (之前)

• 错误处理逻辑在 main.py 中
• 直接返回 Pydantic 原始错误

📝 贡献指南

改进错误处理时：

1. 遵循现有的架构设计
2. 保持安全性和用户友好性
3. 添加相应的测试
4. 更新文档

🎉 总结

通过这次重构：

• 代码更简洁：主文件减少 55% 代码
• 架构更清晰：职责分离，模块化设计
• 安全更可靠：不暴露技术细节
• 体验更友好：清晰的错误提示
• 测试更完善：独立模块易于测试

这是一个生产级的错误处理方案！ 🚀