python-backend-patterns@1.0.0

CLI 安装指南

通过 SkillSPAI CLI 一键安装到你的 AI 编码工具：

npm install -g skillspai

# Codex CLI
skillspai install python-backend-patterns --target codex

# Claude Code
skillspai install python-backend-patterns --target claude

# Cursor
skillspai install python-backend-patterns --target cursor

# Windsurf
skillspai install python-backend-patterns --target windsurf

# OpenCode
skillspai install python-backend-patterns --target opencode

skillspai install python-backend-patterns@1.0.0 --target claude

Skill 内容

# Python 后端开发最佳实践

## 项目结构

```
app/
├── api/            # 路由层，只做请求解析和响应
├── services/       # 业务逻辑层
├── models/         # SQLAlchemy 模型
├── schemas/        # Pydantic 请求/响应模型
├── core/           # 配置、安全、依赖注入
└── utils/          # 工具函数
```

## FastAPI 规范

- 路由函数只做参数解析和响应，业务逻辑放 service 层
- 用 `Depends()` 做依赖注入，不要在路由里直接创建数据库连接
- 请求体用 Pydantic BaseModel，不要用 dict
- 响应统一用 `response_model` 声明返回类型
- 错误用 `HTTPException`，不要返回自定义 JSON

## SQLAlchemy 规范

- 用 async SQLAlchemy（`AsyncSession`），不要用同步 Session
- 关系用 `relationship()` 定义，不要手动 JOIN
- 查询用 `select()` 语法，不要用 `session.query()`
- 迁移用 Alembic，不要手动改数据库
- 软删除用 `deleted_at` 字段，不要真删数据

## 数据验证

- 所有外部输入用 Pydantic 校验
- 分页参数统一用 `PageParams(page: int = 1, size: int = 20)`
- 枚举用 Python `Enum`，不要用字符串常量
- 日期时间统一用 UTC，前端做时区转换

## 安全

- 密码用 `bcrypt` 或 `argon2`，不要用 MD5/SHA1
- JWT token 设置过期时间，不要用永不过期的 token
- CORS 只允许指定域名，不要用 `allow_origins=["*"]`
- SQL 参数化查询，不要拼接 SQL 字符串

## 测试

- 用 `pytest` + `httpx.AsyncClient` 做集成测试
- 测试数据库用 SQLite 内存库或独立的测试数据库
- 每个测试用例独立，不依赖执行顺序
- Mock 外部服务，不要 Mock 数据库

## 常见错误

- 不要在 async 函数里调用同步 I/O（会阻塞事件循环）
- 不要在循环里逐条 INSERT，用 `bulk_insert` 或 `add_all`
- 不要忘记 `await` 异步数据库操作
- 不要在 Pydantic model 里写业务逻辑