Django DRF @action 详解：自定义 ViewSet 方法

在 Django REST Framework（DRF）中，@action 装饰器用于为 ViewSet 添加自定义的 API 端点。相比于 update、create 等默认方法，@action 允许我们定义 更加清晰、语义化 的 API 访问路径，使接口更加易读且符合 RESTful 设计原则。

---

1. @action 的作用

@action 主要用于 自定义 API 端点，避免滥用 update、create 等标准方法，使 API 语义更加清晰。例如：

• POST /users/{id}/assign_roles/ ✅ （自定义用户角色分配接口，语义清晰）
• POST /users/{id}/change_password/ ✅ （单独的修改密码接口）
• GET /users/{id}/permissions/ ✅ （查询用户权限）

---

2. @action 的基本用法

📌 示例：为用户分配角色

from rest_framework.decorators import action
from rest_framework.response import Response
from rest_framework import viewsets, status
from django.contrib.auth.models import User

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

    @action(detail=True, methods=['post'])
    def assign_roles(self, request, pk=None):
        """
        自定义 API 端点：为用户分配角色
        - `detail=True` 表示该方法针对单个用户（即 /users/{id}/assign_roles/）
        - 仅允许 `POST` 方法
        """
        user = self.get_object()
        roles = request.data.get('roles', [])

        # 处理角色分配逻辑（假设 UserRole 是用户角色关联表）
        UserRole.objects.filter(user=user).delete()
        for role_id in roles:
            UserRole.objects.create(user=user, role_id=role_id)

        return Response({"message": "Roles assigned successfully"}, status=status.HTTP_200_OK)

📌 访问路径

方法	访问路径	说明
POST	/users/{id}/assign_roles/	为用户分配角色

---

3. @action 的参数

@action 可以接收多个参数，主要有：

（1）detail=True/False

• detail=True：作用于单个对象，路径格式为 /users/{id}/action_name/
• detail=False：作用于集合，路径格式为 /users/action_name/

@action(detail=True, methods=['post'])
def assign_roles(self, request, pk=None): 
    """ /users/{id}/assign_roles/ """
@action(detail=False, methods=['get'])
def active_users(self, request):  
    """ /users/active_users/ """
    active_users = User.objects.filter(is_active=True)
    serializer = self.get_serializer(active_users, many=True)
    return Response(serializer.data)

---

（2）methods=['get', 'post', 'put', 'patch', 'delete']

@action 默认使用 GET，但可以指定其他方法：

@action(detail=True, methods=['patch'])
def change_password(self, request, pk=None):  
    """ /users/{id}/change_password/ """
    user = self.get_object()
    new_password = request.data.get('password')
    user.set_password(new_password)
    user.save()
    return Response({"message": "Password updated"}, status=status.HTTP_200_OK)

---

（3）permission_classes=[...], authentication_classes=[...]

@action 允许自定义权限和认证策略：

from rest_framework.permissions import IsAdminUser

@action(detail=False, methods=['get'], permission_classes=[IsAdminUser])
def admin_users(self, request):  
    """ /users/admin_users/ 仅管理员可访问 """
    admins = User.objects.filter(is_staff=True)
    serializer = self.get_serializer(admins, many=True)
    return Response(serializer.data)

---

4. @action 与 update 的区别

方法	作用	访问路径	适用场景
update	更新单个用户	PUT /users/{id}/	用户资料更新
@action	自定义操作	POST /users/{id}/assign_roles/	角色分配、修改密码等

📌 最佳实践：

• 简单的用户信息更新 → 用 update
• 特定业务操作（如分配角色、修改密码） → 用 @action

---

5. @action 的最佳实践

✅ （1）单一职责：一个 API 只做一件事

❌ 错误示例（混合多个逻辑）：

def update(self, request, pk=None):
    user = self.get_object()
    user.username = request.data.get('username', user.username)
    user.set_password(request.data.get('password'))
    user.save()

✅ 正确示例（拆分成两个 API）：

@action(detail=True, methods=['patch'])
def change_username(self, request, pk=None):
    user = self.get_object()
    user.username = request.data.get('username', user.username)
    user.save()
    return Response({"message": "Username updated"}, status=status.HTTP_200_OK)

@action(detail=True, methods=['patch'])
def change_password(self, request, pk=None):
    user = self.get_object()
    user.set_password(request.data.get('password'))
    user.save()
    return Response({"message": "Password updated"}, status=status.HTTP_200_OK)

---

✅ （2）语义化 URL

• 用户更新资料 → PUT /users/{id}/
• 分配角色 → POST /users/{id}/assign_roles/
• 查询活跃用户 → GET /users/active_users/
• 修改密码 → POST /users/{id}/change_password/

❌ 避免滥用 update 处理多个逻辑！

---

✅ （3）权限控制

确保敏感操作（如修改密码）有适当的权限：

@action(detail=True, methods=['post'], permission_classes=[IsAuthenticated])
def change_password(self, request, pk=None):
    """ 只有登录用户才能修改密码 """

---

6. 总结

• @action 适用于自定义 API 端点
• 避免滥用 update，拆分独立逻辑
• 更符合 RESTful 设计，使 API 语义清晰
• 可搭配权限、认证等更灵活

👉 结论：@action 是 DRF 中提升代码可读性和 API 设计的重要工具，建议在特定业务场景下使用！ 🚀