---

name: python description: Build, review, and refactor Python backend services. Use for tasks like FastAPI/Flask service setup, API design, request/response schemas, database access (PostgreSQL), migrations, background jobs, observability (logging/metrics/tracing), authentication, configuration, testing, and production hardening.

python

Use this skill for Python 后端服务开发与评审。

Defaults (unless repo dictates otherwise)

• Framework: FastAPI (preferred) or follow existing
• Python: follow repo’s version; prefer modern typing
• API: JSON over HTTP, explicit schemas
• DB: PostgreSQL; prefer explicit migrations

Service structure (recommended)

• app/
  • main.py (app factory, routers)
  • api/ (routers, request/response models)
  • core/ (config, logging, security)
  • db/ (session/engine, repositories)
  • models/ (ORM models if used)
  • schemas/ (Pydantic models)
  • services/ (business logic)
  • integrations/ (3rd party clients)
  • tests/

Workflow

1. Clarify contract

• Endpoints, auth requirements, error model, SLAs.
• Data ownership and persistence requirements.

1. API design

• Version paths (/v1/...) and consistent naming.
• Pydantic schemas: validate on input, shape output explicitly.
• Error responses: stable code + message + optional details.

1. Persistence

• Define schema and migrations (Alembic if used).
• Avoid leaking DB models into API; map to schemas.
• Use indexes for query paths; ensure safe defaults and constraints.

1. Security

• Keep secrets in env vars; never in code.
• AuthN/AuthZ: token validation, scopes/roles.
• Input validation, rate limiting (if relevant), safe logging (no PII).

1. Observability

• Structured logs with request IDs.
• Metrics for latency, error rate, DB timings; tracing if available.

1. Testing

• Unit tests for business logic.
• API tests for endpoints (happy path + errors).
• Deterministic fixtures; avoid flaky time/network dependencies.

Output expectations when making changes

• Prefer small, incremental diffs.
• Update schemas/migrations/tests together.
• Document new env vars and run steps.