dmr-from-drf

从 DRF 迁移到 DMR

概述

逐步将 Django REST Framework 传输层迁移到 django-modern-rest。 除非用户明确要求，否则保持业务逻辑不变。

必需文档（始终优先参考）：

• DMR LLM 文档：https://django-modern-rest.readthedocs.io/llms.txt
• DRF 文档：https://www.django-rest-framework.org
• 本地映射：references/drf-to-dmr-map.md

迁移策略

• 默认模式：严格保持传输层一致。
• 默认保留：路径、方法、请求／响应架构、状态码、标头、身份验证语义、权限语义、限流语义、分页封装、筛选／查询行为。
• 如果用户批准了偏差（例如切换到 DMR 原生错误格式／状态码），则停止强行保留旧行为，并将其记录为 approved drift。
• 绝不引入隐式偏差：必须明确列出每项有意的不一致。
• 不要将保留 DRF 传输层内部实现作为实现策略。 保留可观察到的契约，但使用 DMR + 项目原生库实现。

工作流

清点 DRF 功能范围

• 首先阅读项目 API 入口和 URL 配置。
• 查找以下内容的用法：APIView、GenericAPIView、ViewSet、GenericViewSet、ModelViewSet、@api_view、DRF 路由器、DRF 序列化器类、解析器／渲染器类、身份验证／权限／限流类、DRF 异常处理器钩子。
• 为每个端点建立迁移矩阵：
  • 路径、方法、身份验证、权限、限流、解析器／渲染器行为，
  • 输入 DTO、输出 DTO，
  • 分页／筛选契约，
  • 预期状态码、预期标头，
  • 已知错误路径。

清点项目原生工具（必需）

• 编写适配器之前，检查现有项目库和集成， 找出应为迁移后的传输层提供支持的组件。
• 优先通过 DMR 机制使用项目已在采用的库，而不是自定义封装。
• 示例：
  • 身份验证／RBAC 集成，
  • 限流包，
  • 仓库中已接入的分页和筛选库。

固定可观察行为

• 根据现有测试 + 序列化器 + 路由捕获行为。
• 编码前标记阻塞性不一致：
  • 路由／方法变更，
  • 架构字段变更，
  • 身份验证／权限／限流变更，
  • 分页／筛选响应形状变更，
  • 解析器／渲染器协商变更，
  • 状态码／标头变更。

确定错误策略（必需关卡）

选择一项并在修改前记录：

• strict parity：
  • 保留现有错误状态码／负载语义，
  • 根据需要适配 DMR 处理器／上下文。
• approved DMR-native errors：
  • 使用框架原生错误映射，
  • 相应更新测试和文档中的预期，
  • 仍需保留正常路径行为以及身份验证／权限／限流行为。

按切片迁移（应用或端点组）

• 每次迁移一个边界明确的切片。
• 保持模块布局不变，除非架构／lint 契约要求变更。
• 不要保留体现 DRF 传输层内部实现的类名。 将传输类重命名为中性名称或面向 DMR 的名称。
• 优先采用轻量传输适配器：
  • 保持用例／服务／仓库不变，
  • 仅更改 DTO、控制器和路由配置。

转换序列化器和请求／响应契约

• 将传输 DTO 用法中的 Serializer / ModelSerializer 替换为兼容 DMR 序列化器的显式类型化 DTO。
• 明确映射请求来源：
  • 请求体 Body[...]、查询参数 Query[...]、路径参数 Path[...]、标头 Headers[...]、Cookie Cookies[...]。
• 当响应包含服务器管理的字段时，拆分输入／输出 DTO。
• 保留字段别名、必填／可选行为，以及契约一致性所需的验证约束。

将 DRF 处理器迁移到 DMR

• 将基于函数的 @api_view 端点替换为显式的 Controller[...] 处理器。
• 将 APIView/GenericAPIView/ViewSet 操作替换为 DMR 控制器和路由器组合。
• 保持路由名称和 URL 结构稳定，除非用户要求调整。
• 有意迁移解析器和渲染器的预期行为。
• 有意迁移异常处理行为：
  • 严格一致模式：保留原有状态码和负载。
  • 经批准的行为调整模式：保留 DMR 原生错误，并更新测试。

替换 API 接线

• 将 DRF 路由器注册和 URL 接线替换为 DMR 路由器 + Django URL include 接线。
• 保持命名空间稳定（api:* 名称），除非已批准调整。
• 仅当项目已公开文档/OpenAPI 路由或用户提出要求时，才添加这些路由。

使用原生功能迁移身份验证、权限和限流

• 按端点保留身份验证和权限预期行为。
• 如果项目使用 DRF 的不透明令牌身份验证或任何第三方工具，最好保留相同模型，将 DMR 的默认 Token 模型替换为现有模型。请明确询问用户。
• 除非已批准调整，否则保留限流行为和标头（例如 Retry-After）。
• 保留按 HTTP 方法区分的权限行为和按操作区分的差异。
• 优先通过 DMR 钩子使用项目现有的原生身份验证/限流库。
• 始终在本地开发和测试中启用全局 validate_responses 设置。
• 确保使用 ResponseSpec 显式声明所有额外响应。
• 要求所有响应都通过响应验证。
• 避免将 DRF 兼容层作为最终解决方案。如果无法避免临时兼容层，请明确标记为临时方案，记录替换计划，并将其列入 unresolved gaps。

更新 DMR 工具的测试

• 必要时，将特定于 DRF 的 API 测试假设替换为仓库原生的 Django/DMR 测试入口。
• 将 API 测试夹具和客户端作为迁移的一等范围：保持夹具用途稳定（api_client、身份验证夹具），但将其重新绑定到已迁移的 DMR 技术栈。
• 按端点保留契约断言：状态码、负载、标头、身份验证/权限行为、限流行为、解析器/渲染器行为、分页/筛选语义。
• 确保负向路径测试覆盖已声明的额外响应，并与 ResponseSpec 元数据相符。
• 对于已完全迁移的传输/测试模块，除非明确批准作为临时调整，否则移除持续存在的 DRF 传输导入。

使用仓库原生 CI 入口验证每个迁移切片

• 运行本仓库 CI 使用的相同命令。
• 优先使用官方脚本入口，而非临时拼凑的命令集。
• 如果 CI/测试环境只能在 docker 中运行，请在 docker 中运行。

完成门槛

满足以下条件后，才能将迁移切片标记为完成：

• 代码检查通过。
• 测试通过（或失败已明确获准作为行为调整）。
• 报告已更新。

翻译规则

• 默认不更改业务逻辑。
• 保持传输行为确定且类型明确。
• 避免暗中更改路由规范化行为（尾随斜杠/前缀）。
• 即使错误负载格式发生变化，也要保留身份验证、权限和限流语义。
• 除非已批准调整，否则保留分页封装和游标/页码语义。
• 保留解析器/渲染器协商行为，或明确列出已批准的行为调整。
• 明确说明框架限制（例如 DMR 原生验证行为）。
• 除非用户明确批准作为临时方案，否则不要在已迁移切片中使用 DRF 传输类。
• 不要在已迁移的传输代码中保留绑定到 DRF 的类名。

报告格式（必需）

在每个重要检查点和工作完成时，按以下 3 个部分报告：

1. preserved behavior
2. approved drift
3. unresolved gaps

unresolved gaps 必须列出具体文件/端点及未解决的原因。

迁移注意事项（源自 DRF）

• DRF 路由器通常默认采用尾部斜杠行为；必须准确保留 URL 形式。
• 如果机械地转换必填／可选 DTO 约束，partial=True 更新语义可能会出现偏差。
• 必须保持分页响应封装（count/next/previous/results 及其顺序）稳定，除非已批准偏差。
• 如果未有意移植解析器／渲染器默认设置，内容协商可能会改变行为。
• 必须按操作保留 ViewSet 类中的操作级权限和限流设置，不能只按类保留。
• 必须明确声明并测试带有标头的响应（例如包含 location 或限流标头的响应）。

输出检查清单

• 已将迁移切片中的 DRF 根路由配置替换为 DMR 路由。
• 已将 DRF API 视图／视图集替换为 DMR 控制器。
• 已将迁移端点中的 DRF 传输序列化器替换为 DTO。
• 已保留身份验证／权限／限流行为，或明确批准偏差。
• 已保留分页／筛选和解析器／渲染器行为，或明确批准偏差。
• 已优先评估项目原生功能，并尽可能使用。
• 迁移后的传输层中没有持久化的 DRF 兼容层或绑定 DRF 的命名。
• 仅在需要保持所选策略的等效行为覆盖时才更新测试。
• 已启用响应验证，且所有迁移后的端点响应均通过验证 （包括通过 ResponseSpec 声明的额外响应）。
• 已针对每个切片执行仓库原生 CI 入口。
• 已按规定的 3 个部分格式生成最终报告。
• 成功完成迁移且迁移后的 API 表面通过 CI 后，从项目依赖中移除 djangorestframework，除非用户明确批准保留它。