Django基础教程（127）Django关系和超链接API之页面上浏览API：Django API自助餐开张！手把手教你打造“会自己指路”的接口

Django超链接API实战教程
原创 于 2025-10-14 07:57:22 发布 · 360 阅读 · 6 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
文章标签：

#django #sqlite #数据库

嘿，朋友们！今天我们要聊一个让Django开发者又爱又恨的话题——API开发。别急着关页面！我保证，这绝对不是那种让人昏昏欲睡的技术文档。想象一下，你的API不仅能返回数据，还会“自己指路”，像贴心的导游一样告诉客户端：“想查看用户详情？往这儿走！相关订单？在那边！”是不是很酷？

一、为什么需要“会指路”的API？

还记得我们最初写API的样子吗？手动拼URL，像这样：

{
    "id": 1,
    "name": "张三",
    "order_url": "/api/orders/?user=1"
}

每增加一个接口，就要手动维护一堆URL。一旦路由变更，全线崩盘！这就好比给朋友指路时说：“你先左转，看到红绿灯再右转，走过三个路口...”繁琐又容易出错。

而现在，超链接API让我们的接口变得像网页一样可以“点击跳转”：

{
    "id": 1, 
    "name": "张三",
    "orders": "http://api.example.com/users/1/orders/"
}

客户端不需要提前知道URL规则，跟着链接走就行了！这就是HATEOAS（超媒体作为应用状态引擎）的精髓，让API变得“自描述”。

二、搭建我们的“API自助餐厅”

让我们从头搭建一个真实的例子——一个博客系统。准备食材：

1. 先来点开胃菜：环境准备

确保你已安装Django和DRF（Django REST Framework）：

pip install django djangorestframework

2. 主菜：模型关系设计

我们的博客有三个核心模型：用户（User）、文章（Post）、评论（Comment）。它们之间的关系就像朋友圈：

  • 用户和文章：一个人能发多篇文章（一对多）
  • 文章和评论：一篇文章有多条评论（一对多）
  • 用户和评论：一个人可以留多条评论（一对多）
# models.py
from django.db import models
from django.contrib.auth.models import User

class Post(models.Model):
    author = models.ForeignKey(User, on_delete=models.CASCADE, related_name='posts')
    title = models.CharField(max_length=200)
    content = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)
    
    def __str__(self):
        return self.title

class Comment(models.Model):
    post = models.ForeignKey(Post, on_delete=models.CASCADE, related_name='comments')
    author = models.ForeignKey(User, on_delete=models.CASCADE, related_name='comments')
    content = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)
    
    def __str__(self):
        return f"{self.author.username}对{self.post.title}的评论"

注意这里的related_name参数，它相当于给关系起了个外号，后面序列化时会用到。

3. 秘制酱料：超链接序列化器

传统序列化器只返回数据ID，而超链接序列化器直接返回完整的URL！

# serializers.py
from rest_framework import serializers
from django.contrib.auth.models import User
from .models import Post, Comment

class UserSerializer(serializers.HyperlinkedModelSerializer):
    posts = serializers.HyperlinkedRelatedField(
        many=True, 
        read_only=True,
        view_name='post-detail'  # 对应URLconf中的name
    )
    comments = serializers.HyperlinkedRelatedField(
        many=True,
        read_only=True,
        view_name='comment-detail'
    )
    
    class Meta:
        model = User
        fields = ['url', 'id', 'username', 'email', 'posts', 'comments']
        extra_kwargs = {
            'url': {'view_name': 'user-detail'}
        }

class PostSerializer(serializers.HyperlinkedModelSerializer):
    # 这些字段会自动根据view_name生成超链接
    author = serializers.HyperlinkedRelatedField(
        read_only=True,
        view_name='user-detail'
    )
    comments = serializers.HyperlinkedRelatedField(
        many=True,
        read_only=True,
        view_name='comment-detail'
    )
    
    class Meta:
        model = Post
        fields = ['url', 'id', 'title', 'content', 'author', 'comments', 'created_at']
        extra_kwargs = {
            'url': {'view_name': 'post-detail'}
        }

class CommentSerializer(serializers.HyperlinkedModelSerializer):
    post = serializers.HyperlinkedRelatedField(
        read_only=True,
        view_name='post-detail'
    )
    author = serializers.HyperlinkedRelatedField(
        read_only=True, 
        view_name='user-detail'
    )
    
    class Meta:
        model = Comment
        fields = ['url', 'id', 'content', 'post', 'author', 'created_at']
        extra_kwargs = {
            'url': {'view_name': 'comment-detail'}
        }

看到那些HyperlinkedRelatedField了吗？它们就是生成超链接的魔法棒！

4. 布置餐桌：URL路由配置

超链接API需要能反向解析的URL配置：

# urls.py
from django.urls import path, include
from rest_framework.routers import DefaultRouter
from . import views

router = DefaultRouter()
router.register(r'users', views.UserViewSet)
router.register(r'posts', views.PostViewSet) 
router.register(r'comments', views.CommentViewSet)

urlpatterns = [
    path('api/', include(router.urls)),
    path('api-auth/', include('rest_framework.urls')),
]

DefaultRouter超好用，它自动帮我们生成API根视图和接口URL。

5. 大厨上场：视图集配置

使用视图集（ViewSet）让代码更简洁：

# views.py
from rest_framework import viewsets
from .models import User, Post, Comment
from .serializers import UserSerializer, PostSerializer, CommentSerializer

class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer

class PostViewSet(viewsets.ModelViewSet):
    queryset = Post.objects.all()
    serializer_class = PostSerializer

class CommentViewSet(viewsets.ModelViewSet):
    queryset = Comment.objects.all() 
    serializer_class = CommentSerializer
三、开餐！浏览我们的API

运行服务器python manage.py runserver，访问http://localhost:8000/api/，你会看到DRF提供的酷炫API浏览界面！

API根目录：

{
    "users": "http://localhost:8000/api/users/",
    "posts": "http://localhost:8000/api/posts/", 
    "comments": "http://localhost:8000/api/comments/"
}

点击"users"链接，进入用户列表接口。随便点个用户，你会看到：

{
    "url": "http://localhost:8000/api/users/1/",
    "id": 1,
    "username": "zhangsan",
    "email": "zhangsan@example.com",
    "posts": [
        "http://localhost:8000/api/posts/1/",
        "http://localhost:8000/api/posts/2/"
    ],
    "comments": [
        "http://localhost:8000/api/comments/1/",
        "http://localhost:8000/api/comments/2/" 
    ]
}

看到魔法了吗？点击"posts"里的任何一个链接，都会直接跳转到那篇文章的详情页！

四、高级烹饪技巧

1. 自定义超链接字段

有时候默认行为不满足需求，我们可以自定义：

class PostSerializer(serializers.HyperlinkedModelSerializer):
    # 自定义超链接文本
    author = serializers.HyperlinkedIdentityField(
        view_name='user-detail',
        lookup_field='author_id'
    )
    
    # 添加非超链接字段
    author_name = serializers.CharField(source='author.username', read_only=True)

2. 处理嵌套关系

想要在文章接口中直接显示评论内容，而不是链接？使用嵌套序列化器：

class CommentNestedSerializer(serializers.ModelSerializer):
    class Meta:
        model = Comment
        fields = ['id', 'content', 'author', 'created_at']

class PostSerializer(serializers.HyperlinkedModelSerializer):
    author = serializers.HyperlinkedRelatedField(...)
    comments = CommentNestedSerializer(many=True, read_only=True)

3. 分页与过滤

大量数据时需要分页，在settings.py中配置：

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 20
}
五、为什么这盘菜这么香？
  1. 前后端解耦：前端不需要硬编码URL，后端修改路由不影响前端
  2. 自描述API：新开发者能快速理解接口关系
  3. 可发现性：像浏览网页一样探索API
  4. 维护性好：添加新关系只需修改序列化器
六、常见翻车现场及救援

问题1：收到错误Could not resolve URL for hyperlinked relationship
解决：检查view_name是否正确，确保URLconf中有对应的name

问题2：超链接字段为null
解决：确认序列化器上下文中有request对象，超链接需要完整的绝对路径

问题3：性能问题（N+1查询）
解决：在视图集中使用select_related和prefetch_related：

class PostViewSet(viewsets.ModelViewSet):
    queryset = Post.objects.select_related('author').prefetch_related('comments')
    serializer_class = PostSerializer
结语

恭喜！你现在已经掌握了Django超链接API的烹饪秘籍。从今天起，你的API不再是冷冰冰的数据返回器，而是贴心的“数据导游”。记住，好的API设计就像好的用户体验——让使用者几乎感觉不到它的存在，却总能带他们去想去的地方。

下次当你看到客户端代码里那些硬编码的URL时，可以优雅地甩出这篇教程，说："试试超链接API吧，让接口自己会指路！"

评论
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符
 
红包 添加红包
表情包 插入表情
表情包 代码片
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

值引力

持续创作，多谢支持！

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付：¥1
获取中
扫码支付

您的余额不足，请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值