用途：这是一份 FastAPI 端点设计的惯用模式参考，适合在构建、审查或重构 API 端点时使用，以保证校验、依赖注入与错误处理的一致性。
主要能力：
- Pydantic 模型设计：区分请求模型与响应模型，避免暴露密码哈希、内部 ID 等字段；用 Field 约束长度与范围，用 field_validator 做自定义校验，用 computed_field 生成派生字段，用 model_config = {"from_attributes": True} 启用 ORM 模式；更新模型用 Optional 字段支持部分更新；支持嵌套模型与 StrEnum 枚举。
- 依赖注入：用 Depends 组织数据库会话、认证与角色校验；get_db 以 yield 提供 AsyncSession 并处理提交与回滚；get_current_user 校验令牌；require_role 实现基于角色的访问控制；可组合服务依赖（如 UserService 同时依赖 DB 与当前用户）。
- 异步与同步决策：调用异步 I/O（aiohttp、asyncpg、aiofiles）用 async def；调用同步 I/O（requests、psycopg2、open()）或同步 CPU 密集代码用 def，由 FastAPI 放入线程池；纯计算两者皆可。避免在 async def 中调用同步 I/O 阻塞事件循环。
- 错误处理：用 HTTPException 返回状态码与 detail；定义 AppError 及 NotFoundError、ConflictError 等子类，并通过 @app.exception_handler 统一返回结构化错误体。
- 路由组织：按 routers、models、schemas、services、dependencies 分层；用 APIRouter 设置 prefix 与 tags，在 main.py 中 include_router。
- 后台任务：用 BackgroundTasks.add_task 在返回响应后执行耗时任务，如发送欢迎邮件。
- 分页：用 PaginationParams 定义 page 与 size 及 offset 属性，用泛型 PaginatedResponse 返回 data、total、page、size、pages，配合 count 查询与 offset/limit。
反模式：不做 Pydantic 校验而直接解析原始 dict；返回原始 dict 而非用 response_model；在 async 处理器中使用同步 I/O 库；捕获所有异常并吞掉；不使用依赖注入而硬编码数据库会话或认证检查。
限制：资料为模式参考，未提供安装命令、版本要求、性能数据或收费信息。