dmr-openapi-skeleton

DMR OpenAPI 骨架

概述

根据 OpenAPI 3.1+ 规范，为 django-modern-rest 生成可运行的传输层骨架。刻意保持输出精简：生成类型化 DTO、基础控制器、路由器、文档配置和最简测试，默认不包含任何业务逻辑。

将 django_test_app/server/apps/* 和 tests/* 下的仓库示例作为本地事实来源。选择 dmr 构造时，请阅读 references/framework-patterns.md；决定生成文件应放在哪里时，请阅读 references/project-map.md；当源 OpenAPI 文档具有权威性，且生成项目应尽可能贴近地保留公开契约，以便作为实用样板时，请阅读 references/spec-fidelity.md。

主要框架文档：

• https://django-modern-rest.readthedocs.io/llms.txt

工作流

先阅读规范

• 编辑代码前，先阅读提供的 OpenAPI 文档。
• 确认 openapi 为 3.1.x 或更高版本。如果文档版本较旧、存在歧义或不完整，请在生成文件前说明。
• 提取标签、路径分组、操作 ID、参数、请求体、响应代码、可复用架构和安全声明。
• 尽早识别复杂构造：oneOf、anyOf、allOf、判别器、多种媒体类型、回调和 webhook 部分。

当源规范具有权威性时，进入规范保真模式

• 如果用户提供了现有 OpenAPI 文档，并希望生成的项目能复现该文档，请将规范保真度视为首要要求。
• 生成后，只要两种产物都可用，就将源规范与构建后的架构进行比较。
• 不要擅自规范化路径、删除标签、将多种媒体类型合并为 JSON，或用框架默认值替换源元数据。
• 如果 dmr 添加了源规范中不存在的框架原生文档，要么将其禁用，要么明确告知用户。
• 此模式下的默认目标是让可运行骨架尽可能保持公开契约一致，而不是让每个生成的组件架构完全相同。

生成新项目时搭建环境

• 如果用户要求在一个新建文件夹中创建项目，请创建环境和依赖清单，而不仅仅是源文件。
• 对于新的独立项目，除非用户明确要求使用纯 Django 骨架，否则优先采用 wemake-django-template 作为项目基础。
• 如果是在现有仓库中扩展，或仅在仓库内生成一个新应用，请勿尝试改造为 wemake-django-template。
• 如果目标仓库未强制使用其他工具，优先使用 uv。
• 如果目标仓库已通过 pyproject.toml 使用 Poetry，优先使用 poetry。
• 仅当用户明确要求，或环境有意保持精简时，才退回使用 pip。
• 安装 django-modern-rest 及生成代码所需的额外依赖。
• 生成基于 Pydantic 的代码时，至少安装 django-modern-rest[pydantic]。
• 即使是 Pydantic 项目，也优先同时加入 django-modern-rest[msgspec]，因为本地文档建议使用 msgspec 以提升 JSON 解析和渲染速度。
• 仅当 OpenAPI 安全模型和用户请求要求 JWT 支持时，才加入 django-modern-rest[jwt]。
• 目标版本为 Python 3.11+ 和 Django 5.0+。
• 除非生成的项目必须为 OpenAPI 文档提供静态文件，否则不要将 'dmr' 加入 INSTALLED_APPS。
• 不要仅为了比较源规范与构建后的规范而添加额外的架构验证库。除非仓库中已有这些库，或用户明确要求，否则不要添加 django-modern-rest[openapi]、openapi-spec-validator 或 schemathesis。
• 使用 wemake-django-template 时，应在其结构上添加生成的 DTO、控制器、路由器、文档配置和测试，而不是手动重建项目框架。

规划输出结构

• 参照最接近的现有仓库布局，而不是另创架构。
• 每个有明确边界的区域通常使用一个 Django 应用，可按稳定的标签或首个路径段划分。
• 为每个应用生成 views.py 和 urls.py。
• 如果应用有可复用的请求和响应 DTO，则生成 serializers.py。仅当符合周边代码风格时，才将小型私有辅助模型内联定义。
• 为每个可运行的项目骨架生成配置 OpenAPI 文档的根 urls.py。
• 除非用户提出更多要求，否则仅为路由、架构和文档冒烟测试生成最精简的测试。

有意选择序列化器

• 默认优先使用 PydanticSerializer。
• 仅当仓库已将 MsgspecSerializer 作为标准，或用户明确提出要求时，才继续使用它。
• 对于联合类型、判别器、别名、可空性、丰富字段约束或混合内容模型等复杂 OpenAPI 3.1 特性，回退到 PydanticSerializer。
• 如果源规范包含 XML 或其他非 JSON 媒体类型，则应独立于解析器和渲染器策略来选择序列化器。仅靠选择序列化器无法保留内容协商。

根据 OpenAPI 部分生成 DTO

• 将请求正文映射到 Body[...]。
• 将查询参数映射到 Query[...]。
• 将路径参数映射到 Path[...]。
• 将标头参数映射到 Headers[...]。
• 将 Cookie 参数映射到 Cookies[...]。
• 在各操作间复用共享架构，而不是重复定义类。
• 保留线格式字段名。仅当架构名称不是有效或易读的 Python 属性时，才引入别名。
• 只要所选序列化器能够妥善支持，就应根据规范编码验证约束。
• 如果响应中增加了标识符、时间戳、令牌、URL 或派生值等由服务器管理的字段，则应拆分输入和输出 DTO。
• 如果可复用架构用于驱动请求和响应 DTO，就应予以保留。如果公共 API 契约已经得到保留，则无需为了与 components.schemas 完全字面一致而优化。

使用正确的 dmr 构造生成视图

• 尽量减少 Controller 的数量。
• 每个操作使用一个类。让路由器负责组合，而不是构建职责混杂的庞大控制器。
• 当 operationId 稳定且明确时，根据它命名类；否则，根据资源和动词派生名称，例如 UserListController、UserCreateController 或 InvoiceRetrieveController。

生成骨架行为，而非虚构业务逻辑

• 运行时处理器应仅负责传输，并保持确定性。
• 返回符合架构的占位数据、回显的请求数据或空集合。
• 对 204 或 304 类型的端点，使用 @modify(status_code=HTTPStatus.NO_CONTENT) 和 -> None。
• 仅在确实需要底层响应构造时，才使用 self.to_response(...)。
• 在持久化、编排、身份验证后端或外部集成通常开始的位置，留下简短的 TODO 注释。
• 除非用户明确要求，否则绝不生成领域工作流、服务调用、数据访问逻辑、定价规则、权限规则或副作用编排。
• 除非用户明确要求，否则不要虚构 Django 模型、服务、仓储或复杂的身份验证实现。

生成路由器并配置项目

• 使用 Router([...], prefix='.../') 构建应用路由。
• 在路由器内部按本地代码的写法使用 path(...) 或 re_path(...)。
• 除非周边项目明确省略，否则生成的路由应保留尾部斜杠。
• 在项目根目录中使用 include((router.urls, 'app_name'), namespace='...') 引入应用路由器。
• 确保生成的可运行骨架始终提供文档：配置 build_schema(...)、OpenAPIJsonView、RedocView、SwaggerView 和 ScalarView。
• 如果源规范具有权威性，应保留其公开路径约定。除非用户明确要求更改公开 API 形式，否则不要添加 /api/ 前缀、尾部斜杠或 kebab-case 改写。

按需生成可运行的引导文件

• 搭建全新项目时，还应生成与所选工具一致的 pyproject.toml 或等效的包管理器配置文件。
• 如果尚不存在，则生成 manage.py、Django 设置、根目录 urls.py 和应用包初始化文件。
• 仅当项目需要公开 OpenAPI UI 时，才配置文档端点。
• 在最终回复中添加简短的运行说明，并提供准确的命令，例如 uv run python manage.py runserver 或 poetry run python manage.py runserver。

生成最小化验证

• 为每个重要路由组添加一个冒烟测试，检查状态码和响应结构。
• 生成文档端点时，添加一个 OpenAPI 冒烟测试。
• 仅当代码库已使用 Schemathesis 或用户明确要求时，才添加 Schemathesis 契约测试。
• 当源规范具有权威性时，在任务完成前将生成的架构与源规范进行比较。报告路径、媒体类型、响应码、标头、安全性、标签、服务器和顶层元数据方面的差异。
• 在可运行骨架中，为 openapi、redoc、swagger 和 scalar 端点添加文档可用性冒烟检查。
• 不要要求使用外部验证工具进行此项比较。优先直接检查架构并执行冒烟测试。

完成前实施实用的保真度检查

• 将以下差异视为阻断性问题：公开路径约定缺失或发生变化、源方法缺失、源主要媒体类型缺失、重要的源响应状态码缺失、会影响客户端的源响应标头缺失、源安全方案或操作级安全性缺失、重要的顶层元数据（info、externalDocs、servers、tags）缺失，或文档端点无法打开。
• 如果请求和响应 DTO、媒体类型及公开操作仍足够忠实且可用于实际脚手架，则将内部组件布局差异视为非阻断性问题。
• 经过简要说明后，可接受序列化器生成的外观元数据差异（例如额外的架构 title 键）。
• 如果仍存在阻断性差异，应继续迭代，或请用户针对具体差异明确批准偏离。
• 在剩余差异得到解决或用户明确接受之前，不要声称任务已完成。

翻译规则

• 当处理器返回序列化器可以渲染的普通 Python 值时，直接标注方法的返回类型。
• 使用 responses = (...)、@modify(extra_responses=[...]) 或 @validate(...) 通过 ResponseSpec 记录其他响应。
• 保持无请求体端点符合 HTTP 规则。对于通常禁止请求体的方法，不要附加 Body[...]，除非规范确实要求这样做，且用户接受显式的 HttpSpec 覆盖。
• 如果仓库已有身份验证后端，请复用。否则，用简短的 TODO 注明已声明的安全要求，而不要臆造后端。
• 优先采用简单的 JSON 输出。只有在规范确实要求多种表示形式，或仓库已有内容协商模式时，才生成特定于内容协商的解析器或渲染器代码。
• 路由名称使用 snake_case，并保持稳定。尽可能从 operationId 推导名称。
• 对于新项目，安装命令应与本地文档保持一致： uv add 'django-modern-rest[msgspec, openapi]'、 poetry add 'django-modern-rest[msgspec, openapi]' 或 pip install 'django-modern-rest[msgspec, openapi]'， 然后按需添加额外项。
• 使用 OpenAPIConfig 保留顶层源元数据：title、version、summary、description、terms_of_service、contact、license、external_docs、servers 和 tags。
• 如果源规范使用多种响应媒体类型（例如 application/json 和 application/xml），则生成匹配的解析器和渲染器，或明确说明保真度有限。不要悄悄将契约简化为仅支持 JSON。
• 当源规范声明 application/x-www-form-urlencoded 时，使用内置支持；并在生成的端点契约中明确保留 application/octet-stream 或文件类请求体。
• 对于库不支持且目标项目尚未实现的媒体类型，在生成代码前请用户选择一种脚手架模式： minimal-working 模式：生成最简透传解析器和渲染器占位代码，使端点仍可通过 curl 调用，同时标记为 TODO。 strict-stub 模式：生成会引发 NotImplementedError 的解析器和渲染器存根。
• 针对首个不支持的媒体类型，必须先使用以下问题模板： Unsupported media type "<media_type>" is not implemented in this project. Choose scaffold mode: "minimal-working" (callable TODO placeholder) or "strict-stub" (NotImplementedError stub).
• 不要为未知媒体类型实现完整的编解码逻辑。实现仍由用户负责。
• 默认使用 DMR 错误模型。优先使用 dmr.errors.ErrorModel、APIError 和相关内置错误机制，而不是自定义源规范专用的错误 DTO，除非用户明确要求保留自定义错误架构。
• 使用 ResponseSpec(..., headers={...}) 保留文档中定义的响应标头，不要将其省略。
• 仅当 DMR 语义响应能改进可运行的脚手架，且用户接受由此产生的差异时，才保留它们。否则使用 DMR_SETTINGS = {Settings.semantic_responses: False} 禁用。
• 通过生成占位身份验证类来保留文档中定义的安全方案；这些类应通过 security_scheme 和 security_requirement 暴露源 OpenAPI 契约，即使运行时身份验证逻辑仍为 TODO。

输出检查清单

• 如果请求是创建全新项目，请创建或更新环境清单。
• 为所有影响路由的请求和响应模型创建符合架构规范的 DTO 类。
• 创建包含带类型控制器和占位实现的 views.py。
• 为每个生成的应用创建包含 Router 配置的 urls.py。
• 仅当请求是创建可运行的项目骨架时，才更新项目根 URL。
• 添加最精简的测试，或说明未添加测试的原因。
• 如果提供了源规范，请确认构建的架构是否保留了路径、顶层元数据、标签、服务器、安全方案、响应标头、媒体类型和空响应体语义。
• 确认生成的可运行项目骨架中提供了文档端点。
• 对于由源驱动的生成，请提供简短的保真度摘要，分为： 保留的契约, 需要用户批准。