Django Ninja 中处理 PATCH 请求与可选字段的最佳实践

在 Django Ninja 框架中处理 PATCH 请求时，开发者经常会遇到一个常见问题：如何区分客户端想要将字段设置为 None 和客户端根本没有发送该字段的情况。这个问题在 RESTful API 设计中尤为重要，因为 PATCH 请求的本意是部分更新资源，而不是完全替换。

问题背景

当使用 Django Ninja 的 ModelSchema 并设置 fields_optional="__all__" 时，请求负载会包含所有可能的键，即使客户端没有发送某些字段，这些未发送的字段也会被设置为 None。这使得服务器无法区分以下两种情况：

1. 客户端明确想要将字段值设置为 None
2. 客户端没有发送该字段，意味着不应修改该字段

解决方案探索

使用 exclude_unset 参数

Django Ninja 提供了 .dict(exclude_unset=True) 方法，可以过滤掉未设置的字段。这是目前最常用的解决方案：

@api.patch("/{id}", response=RespSchema)
def patch_view(request, employee_id, body: ReqSchema):
    employee = get_object_or_404(Employee, id=employee_id)
    filtered_dict = body.dict(exclude_unset=True)
    for attr, value in filtered_dict.items():
        setattr(employee, attr, value)

这种方法有效地区分了未设置的字段和显式设置为 None 的字段。

可选字段与默认值的区别

在定义 Schema 时，开发者需要注意两种不同的字段定义方式：

1. 可选字段：使用 Optional[str] 表示该字段可以完全从请求中省略
2. 可空字段：使用 str = None 表示该字段必须提供，但可以设置为 None

正确的用法应该是：

class TheSchema(Schema):
    optional_field: Optional[str]  # 可以省略
    nullable_field: Optional[str] = None  # 必须提供但可为None

未来可能的改进

Django Ninja 可能会引入 PatchDict 类型标记，使 PATCH 操作更加优雅：

@api.patch("/patch")
def patch(request, payload: PatchDict[SomeSchema]):
    print(payload)  # 只包含客户端实际发送的字段

这种设计将使 PATCH 操作更加直观，自动处理字段过滤逻辑。

实际应用建议

对于当前版本的 Django Ninja，建议采用以下模式处理 PATCH 请求：

1. 为 PATCH 操作创建专门的 Schema，所有字段都设为 Optional
2. 在视图函数中使用 .dict(exclude_unset=True) 获取实际修改的字段
3. 使用循环将这些字段应用到模型实例

class EmployeePatchSchema(Schema):
    name: Optional[str]
    age: Optional[int]
    department: Optional[str]

@api.patch("/employees/{id}")
def update_employee(request, id: int, payload: EmployeePatchSchema):
    employee = get_object_or_404(Employee, id=id)
    update_data = payload.dict(exclude_unset=True)
    for field, value in update_data.items():
        setattr(employee, field, value)
    employee.save()
    return employee

这种方法既保持了代码的简洁性，又正确处理了部分更新的需求。

总结

Django Ninja 提供了灵活的工具来处理 PATCH 请求和可选字段。通过合理使用 Schema 定义和 .dict(exclude_unset=True) 方法，开发者可以轻松实现符合 REST 原则的部分更新操作。未来随着框架的发展，可能会提供更加简洁的语法糖来进一步简化这一常见模式。