Django REST Framework 教程：API 关系与超链接设计-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00117/article/details/148360558

Django REST Framework 教程：API 关系与超链接设计

django-rest-framework encode/django-rest-framework: Django REST framework 是一个强大的 Web API 开发工具包，专为 Django 框架设计，提供了一套丰富的功能集来构建 Web API，包括序列化、分页、权限管理等。项目地址: https://gitcode.com/gh_mirrors/dj/django-rest-framework

前言

在构建现代 Web API 时，如何优雅地处理资源之间的关系是一个关键设计问题。Django REST Framework 提供了多种方式来表示这些关系，本教程将重点介绍最符合 REST 架构风格的超链接方式。

为什么需要超链接 API？

在之前的实现中，我们使用主键（Primary Key）来表示资源间的关系。这种方式虽然简单，但存在几个问题：

客户端需要预先知道 API 的结构才能构建请求
缺乏自描述性，不利于 API 的发现
不符合 REST 架构中"超媒体作为应用状态引擎"（HATEOAS）的原则

超链接 API 通过提供完整的 URL 来解决这些问题，使 API 更具自描述性和可发现性。

创建 API 入口端点

良好的 API 设计应该有一个明确的入口点。我们可以创建一个根端点来展示所有可用的资源：

from rest_framework.decorators import api_view
from rest_framework.response import Response
from rest_framework.reverse import reverse

@api_view(['GET'])
def api_root(request, format=None):
    return Response({
        'users': reverse('user-list', request=request, format=format),
        'snippets': reverse('snippet-list', request=request, format=format)
    })

这里使用了 reverse 函数来生成完整的 URL，而不是硬编码路径。这种方式更加灵活，能自动适应不同的部署环境。

实现代码高亮端点

代码片段高亮是一个特殊的需求，因为它需要返回 HTML 而不是 JSON。我们可以创建一个专门的视图来处理这个需求：

from rest_framework import renderers

class SnippetHighlight(generics.GenericAPIView):
    queryset = Snippet.objects.all()
    renderer_classes = [renderers.StaticHTMLRenderer]

    def get(self, request, *args, **kwargs):
        snippet = self.get_object()
        return Response(snippet.highlighted)

这个视图使用了 StaticHTMLRenderer，它会直接将响应内容作为 HTML 返回，而不进行额外的模板处理。

超链接序列化器

Django REST Framework 提供了 HyperlinkedModelSerializer 来简化超链接 API 的实现。它与常规的 ModelSerializer 主要区别在于：

默认不包含 id 字段
自动添加 url 字段（使用 HyperlinkedIdentityField）
关系字段使用 HyperlinkedRelatedField 而不是 PrimaryKeyRelatedField

改造后的序列化器示例：

class SnippetSerializer(serializers.HyperlinkedModelSerializer):
    owner = serializers.ReadOnlyField(source='owner.username')
    highlight = serializers.HyperlinkedIdentityField(
        view_name='snippet-highlight', 
        format='html'
    )

    class Meta:
        model = Snippet
        fields = ['url', 'id', 'highlight', 'owner',
                 'title', 'code', 'linenos', 'language', 'style']

class UserSerializer(serializers.HyperlinkedModelSerializer):
    snippets = serializers.HyperlinkedRelatedField(
        many=True, 
        view_name='snippet-detail', 
        read_only=True
    )

    class Meta:
        model = User
        fields = ['url', 'id', 'username', 'snippets']

URL 命名的重要性

在超链接 API 中，URL 模式的命名至关重要，因为序列化器需要通过名称来反向查找 URL。确保为所有 URL 模式定义清晰、一致的名称：

urlpatterns = format_suffix_patterns([
    path('', views.api_root),
    path('snippets/', views.SnippetList.as_view(), name='snippet-list'),
    path('snippets/<int:pk>/', views.SnippetDetail.as_view(), name='snippet-detail'),
    path('snippets/<int:pk>/highlight/', views.SnippetHighlight.as_view(), name='snippet-highlight'),
    path('users/', views.UserList.as_view(), name='user-list'),
    path('users/<int:pk>/', views.UserDetail.as_view(), name='user-detail')
])

分页配置

对于可能返回大量结果的列表视图，分页是必不可少的。Django REST Framework 提供了灵活的分页配置：

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 10
}

这个配置会全局应用分页，每页默认显示 10 条记录。你也可以为特定视图自定义分页行为。

测试你的超链接 API

完成上述修改后，你可以通过浏览器的可浏览 API 界面来测试：

根端点会显示所有可用的资源链接
代码片段详情会包含高亮链接
用户详情会包含其所有代码片段的链接

这种设计使得 API 更加自描述，客户端可以通过跟随链接来探索整个 API，而不需要预先知道其结构。

总结

通过本教程，我们实现了：

创建了统一的 API 入口点
添加了专门的代码高亮端点
使用超链接替代主键来表示资源关系
配置了合理的分页设置

这种设计使 API 更加符合 REST 原则，提高了可用性和可发现性。在后续教程中，我们将介绍如何使用视图集(ViewSets)和路由器(Routers)来进一步简化代码。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考