Django Ninja 中实现基于权限的响应序列化控制

在 Django Ninja 项目中，开发者经常需要根据用户权限动态控制 API 响应内容。本文将深入探讨如何利用 Pydantic 2.7 引入的序列化上下文功能，在 Django Ninja 框架中实现精细化的响应字段权限控制。

需求背景

现代 Web 应用通常需要根据用户角色和权限动态调整 API 响应内容。例如，某些敏感字段只应对管理员可见，而普通用户则不应看到这些字段。传统做法是在视图层进行数据过滤，但这会导致业务逻辑分散且难以维护。

Django Ninja 作为基于 Pydantic 的 API 框架，提供了强大的数据验证和序列化能力。最新版 Pydantic 2.7 引入了序列化上下文功能，为我们在模型序列化阶段实现权限控制提供了新的可能性。

技术实现方案

1. 基础权限控制方案

最简单的权限控制方式是在 Schema 类中直接定义字段解析逻辑：

class MyResponse(Schema):
    public_field: str
    secret_field: Optional[str] = None

    @staticmethod
    def resolve_secret_field(obj, context):
        request = context['request']
        if not request.user.is_superuser:
            return None
        return obj.secret_field

这种方法简单直接，但当权限逻辑复杂或字段众多时，会导致 Schema 类臃肿且难以维护。

2. 基于序列化上下文的进阶方案

更优雅的解决方案是利用 Pydantic 2.7 的 model_serializer 装饰器和序列化上下文：

class ResponseSchema(Schema):
    field_available_for_everyone: str
    field_under_permission: str

    class Permissions:
        field_under_permission = UserPermission('can_view_secret_field')

    @model_serializer(mode="wrap")
    def serialize(self, handler, info):
        serialized = handler(self)
        
        if info.context is not None and info.context.request is not None:
            excludes = get_excludes_by_permissions(self, info.context.request.user)
            for e in excludes:
                serialized.pop(e)
        
        return serialized

这种实现方式有以下优势：

• 权限逻辑集中管理，通过 Permissions 类清晰定义每个字段的权限要求
• 序列化过程可定制，可以在默认序列化后进一步处理数据
• 保持了 Schema 类的整洁性，业务逻辑与数据结构定义分离

3. 框架集成方案

要实现上述功能，需要对 Django Ninja 框架进行少量扩展。核心是在 Operation 类中将请求对象传递给序列化上下文：

# 在 Operation._result_to_response 方法中
result = schema.model_dump(result, context={'request': request})

这种扩展虽然简单，但需要谨慎处理框架的继承关系，确保不影响现有功能。

最佳实践建议

1. 权限定义标准化：建议创建统一的权限定义方式，如示例中的 Permissions 类，便于团队协作和维护。

2. 性能考量：对于字段众多的复杂 Schema，应考虑权限检查的性能影响，必要时可缓存权限计算结果。

3. 错误处理：在序列化过程中处理权限时，应妥善处理异常情况，避免泄露敏感信息。

4. 测试覆盖：权限相关的序列化逻辑应有充分的测试覆盖，确保不同权限用户获取正确的响应。

总结

通过结合 Django Ninja 和 Pydantic 的最新功能，我们可以构建出既灵活又安全的 API 权限控制系统。这种基于序列化上下文的解决方案不仅保持了代码的整洁性，还提供了强大的扩展能力，适合中大型项目的权限管理需求。开发者可以根据项目实际情况选择适合的实现方案，平衡开发效率和运行时性能。