SuperAPI AI 工具集

setting-up-python-backends

编程与开发

查看项目

更新于 10-16 04:55

技能介绍

用途:这是 myai 的 setting-up-backends 的 Python 专用扩展,只补充 Python 侧框架选择、库选型和代码模式。使用前要求先加载 setting-up-backends,并依赖 engineering-principles 与 architecting-changes;它本身又是 setting-up-python-projects 的后端专用扩展,后端仓库从此开始,通用 Python 启动内容按需从 setting-up-python-projects 取。

主要能力:框架选择上,FastAPI 是多数服务 API 的默认稳妥选择;Django 适用于一开始就有大量认证、管理后台、会话和 CRUD 的场景;Starlette 用于刻意的薄边缘构建,不作默认。默认技术栈:FastAPI + uvicorn;HTTP 边缘用 pydantic 模型,配置与非框架外部载荷解码用 msgspec.Struct;核心用 dataclass(frozen=True, slots=True) 与 Result[T, E];自有关系型持久化用 SQLAlchemy 2 + Alembic;出站 HTTP 用 httpx;日志沿用仓库既有 src/<package>/shared/logging;测试用 pytest、pytest-asyncio,并通过真实应用接线做集成测试;工具链用 uv、poethepoet、basedpyright、ruff。pydantic 请求/响应 DTO 保持在 HTTP 边界并立即转换为无框架类型结构。

目录布局:src/appname/ 下分 api(app.py、routes、schemas、errors.py)、domain(models.py、services.py、errors.py)、infrastructure(config.py、logging.py、db/、clients/)、workers/main.py、bootstrap.py,另有 tests(integration、unit、fixtures)与 migrations/。不需要的部分可省略:无数据库则省 db/ 与 migrations/,无 worker 则省 workers/。首批文件包括 create_app() 的 api/app.py、含 /healthz 的 api/routes/health.py、含 create_services() 与应用接线的 bootstrap.py、domain/models.py 与一个小的服务/用例模块、把环境变量解析为类型化设置的 infrastructure/config.py,仅有持久化时才加 DB 与迁移文件,以及一个 API 冒烟测试和一个领域测试。

接线与边界:create_app() 只组装 HTTP 层;bootstrap.py 负责设置、DB/会话工厂、外部客户端与服务的接线;默认不用 DI 框架,用构造函数注入和单一组合根;main.py 或 ASGI 入口保持轻薄。请求/响应 schema 不是领域模型;领域服务中不得出现 Request、Response、Depends、ORM 会话或框架认证对象;请求数据与认证/会话状态在边缘转换;worker 只是另一种适配器,不是独立业务逻辑栈;CLI/管理脚本涉及同一工作流时应调用同一核心服务。

迁移与运维:服务自有关系型 DB 时尽早初始化 Alembic;尽早加健康与就绪端点;开发运行、lint、测试、迁移命令放进 Poe 任务;需要时容器化,v1 保持 Linux 优先且朴素。默认延后:队列与后台任务栈、缓存层、指标/追踪厂商、事件总线或 CQRS、多租户、超出基本成长空间的 API 版本策略、生成 SDK 与 OpenAPI 定制、Kubernetes 专门指导,等确有需要再加。交接:day-2 后端架构用 building-backends,API/CLI/自动化共享核心用 building-multi-ui-apps,实现规则用 writing-python-code。具体版本、收费与平台支持情况暂未提供。