backend-python

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Backend Python

Python后端

Use this pack for Python backend work: REST APIs, service layers, auth flows, async I/O, model-serving edges, background work, and backend delivery patterns that live in the Python ecosystem.

Defer first-pass route choice and lane selection to

../../reference/routing-matrix.md

This is the general Python backend pack for the repo. Use the overlays in

reference/

to tune decisions for FastAPI or the Django and Flask family while preserving the same expectations for contracts, validation, documentation, and production behavior.

使用此工具包进行Python后端开发工作：REST API、服务层、认证流程、异步I/O、模型服务边缘、后台任务，以及Python生态系统中的后端交付模式。

初始路由选择和方案选择请参考

../../reference/routing-matrix.md

。

这是仓库的通用Python后端工具包。使用

reference/

中的覆盖配置来针对FastAPI或Django/Flask系列调整决策，同时保持对契约、校验、文档和生产行为的一致要求。

Setup posture

搭建原则

Prefer modernizing, refining, or extending an existing project in place.
Treat scaffold,
```
create
```
,
```
init
```
, or
```
new
```
flows as greenfield-only and explicit-request-only. Defer to
```
.opencode/reference/project-setup-policy.md
```
.

优先在现有项目基础上进行现代化改造、优化或扩展。
仅在全新项目且明确请求的情况下使用脚手架、
```
create
```
、
```
init
```
或
```
new
```
流程。具体请遵循
```
.opencode/reference/project-setup-policy.md
```
。

Core focus

核心关注点

Design API contracts that are easy to reason about from schema model to handler to service layer.
Keep request and response validation explicit with typed models, serializers, or forms that fit the framework.
Choose authentication and authorization flows deliberately: OAuth2, JWTs, sessions, service credentials, or scoped policies.
Be intentional about async behavior, database session lifecycle, background tasks, and queue boundaries.
Keep documentation, configuration, and operational visibility close to the backend surface.

设计从schema模型到处理器再到服务层都易于理解的API契约。
使用符合框架的类型化模型、序列化器或表单，明确请求和响应校验规则。
谨慎选择认证与授权流程：OAuth2、JWT、会话、服务凭证或范围化策略。
有意识地处理异步行为、数据库会话生命周期、后台任务和队列边界。
确保文档、配置和运维可见性贴近后端实现层面。

Shared Python backend standards

通用Python后端标准

Keep type hints, schema models, and domain boundaries readable instead of letting framework shortcuts blur them together.
Separate API models from persistence models when that separation protects contract stability and security.
Use explicit validation at every external boundary and keep sensitive fields filtered out of outward-facing models.
Publish OpenAPI or equally clear endpoint documentation for shared services and public APIs.
Choose async because the workload benefits from it, not because the framework makes it available.
Make auth, permission checks, token refresh, and background processing visible in the code path rather than implied by defaults.

保持类型提示、schema模型和领域边界的可读性，避免因框架捷径导致边界模糊。
当分离API模型与持久化模型能保障契约稳定性和安全性时，进行分离。
在所有外部边界处使用显式校验，并确保敏感字段不会出现在对外模型中。
为共享服务和公开API发布OpenAPI或同等清晰的端点文档。
选择异步方案是因为工作负载能从中受益，而非仅仅因为框架支持。
确保认证、权限检查、令牌刷新和后台处理在代码路径中可见，而非依赖默认隐含行为。

Default workflow

默认工作流程

Inspect the existing package layout, schema approach, and runtime model.

Choose the closest overlay from

reference/fastapi.md

reference/django-flask.md

Define the contract surface, validation rules, auth flow, and sync or async behavior before expanding the service layer.
Implement handlers, service boundaries, and documentation together so the backend remains understandable under change.
Run
```
review-work
```
after substantial backend changes.

检查现有包结构、schema方案和运行时模型。

从

reference/fastapi.md

或

reference/django-flask.md

中选择最匹配的覆盖配置。

在扩展服务层之前，定义契约范围、校验规则、认证流程以及同步或异步行为。
同步实现处理器、服务边界和文档，确保后端在变更时仍保持可理解性。
在完成重大后端变更后运行
```
review-work
```
。

Collaboration in this repo

仓库协作规范

Use
```
Explore
```
before editing so the new work follows local module and service patterns.
Use
```
Librarian
```
or
```
Context7
```
for framework docs, protocol details, and library tradeoffs.
Pair with
```
architecture-integration
```
when the task is really about service boundaries, client contracts, or cross-system coordination.

编辑前先使用
```
Explore
```
，确保新工作遵循本地模块和服务模式。
使用
```
Librarian
```
或
```
Context7
```
获取框架文档、协议细节和库的权衡分析。
当任务涉及服务边界、客户端契约或跨系统协调时，与
```
architecture-integration
```
配合。

Overlays

覆盖配置

```
reference/fastapi.md
```
for async-first APIs, Pydantic models, dependency-driven auth, and SQLAlchemy or async service patterns.
```
reference/django-flask.md
```
for Django or Flask services where batteries-included app structure or explicit extension-based composition shapes the backend.

```
reference/fastapi.md
```
：适用于异步优先API、Pydantic模型、依赖驱动认证，以及SQLAlchemy或异步服务模式。
```
reference/django-flask.md
```
：适用于Django或Flask服务，这类服务采用内置应用结构或显式基于扩展的组合方式构建后端。

Guardrails

约束规则

Do not force every Python backend into one async pattern when the runtime and workload do not need it.
Do not leak ORM entities, request objects, or framework globals across the whole service layer.
Do not let framework convenience hide contract drift, weak validation, or unsafe auth behavior.

当运行时和工作负载不需要时，不要将所有Python后端强制纳入单一异步模式。
不要让ORM实体、请求对象或框架全局变量渗透到整个服务层。
不要因框架的便利性而掩盖契约偏差、弱校验或不安全的认证行为。