djangochannelsrestframework 前后端实战：搭配 dcrf-client 构建实时 Web 应用的完整教程

djangochannelsrestframework 前后端实战搭配 dcrf-client 构建实时 Web 应用的完整教程【免费下载链接】djangochannelsrestframeworkA Rest-framework for websockets using Django channels-v4项目地址: https://gitcode.com/gh_mirrors/dj/djangochannelsrestframeworkdjangochannelsrestframework简称 DCRF是一个基于 Django Channels v4 的 WebSocket 接口框架它把 Django REST Framework 的成熟体验带到了实时通信世界你不再需要手写复杂的receive_json分发逻辑而是像写 DRF ViewSet 一样通过 Mixin 和GenericAsyncAPIConsumer快速搭建一套完整的 WebSocket API。本文将以一个真实的前后端分离项目为例完整演示从服务端构建接口、到前端使用dcrf-client调用接口、再到模型实时订阅推送的全过程让新手也能快速上手实时 Web 应用开发。为什么选择 djangochannelsrestframework在传统 Web 开发中Django REST Framework 是构建 HTTP API 的事实标准但当业务需要实时推送聊天、通知、在线协作、订单状态时HTTP 轮询效率低下WebSocket 才是正解。djangochannelsrestframework 的价值在于API 风格与 DRF 高度一致熟悉 DRF 的开发者几乎零成本迁移免去繁琐的消息分发内置action机制一条 JSON 消息即可触发一个接口方法模型层实时推送通过observer模块数据库一有变化就自动推送给前端原生支持权限校验IsAuthenticated、AllowAny开箱即用。一句话总结它让你用写 REST API 的方式写出一套实时 API。环境准备最快速的安装配置方法 ⚙️开始之前请确保你的环境满足Python 3.8Django 3.2 与 Channels 4.xdjangochannelsrestframework安装命令非常简单一条 pip 搞定pip install djangochannelsrestframework由于 DCRF 依赖 Django Channels如果你的项目还没配置 ASGI 应用asgi.py需要先按 Channels 官方文档完成基础接入。 小提示DCRF 的全局配置在 settings.py 中定义你可以通过 Django 的DJANGO_CHANNELS_REST_API配置项调整默认权限类、分页大小等例如DEFAULT_PERMISSION_CLASSES默认是AllowAny。服务端第一步创建你的第一个 WebSocket API DCRF 的核心是GenericAsyncAPIConsumer它位于 generics.py作用类似于 DRF 的GenericAPIView。搭配 mixins.py 中的 CRUD Mixin几行代码就能得到完整的增删改查接口。1. 编写序列化器沿用你熟悉的 DRF Serializer完全不用改动# serializers.py from rest_framework import serializers from django.contrib.auth.models import User class UserSerializer(serializers.ModelSerializer): class Meta: model User fields [id, username, email, password] extra_kwargs {password: {write_only: True}}2. 组装 Consumer# consumers.py from django.contrib.auth.models import User from djangochannelsrestframework.generics import GenericAsyncAPIConsumer from djangochannelsrestframework.mixins import ( ListModelMixin, RetrieveModelMixin, PatchModelMixin, UpdateModelMixin, CreateModelMixin, DeleteModelMixin, ) from .serializers import UserSerializer class UserConsumer( ListModelMixin, RetrieveModelMixin, PatchModelMixin, UpdateModelMixin, CreateModelMixin, DeleteModelMixin, GenericAsyncAPIConsumer, ): queryset User.objects.all() serializer_class UserSerializer每个 Mixin 对应一个 action 动作Mixin动作说明ListModelMixinlist获取全部实例RetrieveModelMixinretrieve按 pk 获取单个实例CreateModelMixincreate创建实例PatchModelMixinpatch部分更新UpdateModelMixinupdate整体更新DeleteModelMixindelete删除实例3. 注册路由# routing.py from django.urls import re_path from . import consumers websocket_urlpatterns [ re_path(r^ws/$, consumers.UserConsumer.as_asgi()), ]⚠️ 注意在应用配置中声明 Consumer 时必须使用.as_asgi()类方法如UserConsumer.as_asgi()不要在任何代码里创建UserConsumer()实例。前端实战dcrf-client 快速接入指南 服务端就绪后前端就该登场了。这里推荐使用dcrf-client—— 一个专门为 DCRF 打造的 JavaScript 客户端库它帮我们封装了 WebSocket 连接、JSON 序列化、request_id 匹配等繁琐细节。dcrf-client 最简连接示例import { APIConsumer } from dcrf-client; const consumer new APIConsumer({ url: ws://localhost:8000/ws/, }); // 调用 list 动作获取用户列表 const response await consumer.call(list, {}); console.log(response.data); // 创建用户 const created await consumer.call(create, { data: { username: newuser, password: test123456, email: newexample.com, }, }); console.log(created.response_status); // 201dcrf-client 的核心优势自动管理 request_id每个请求自动带上唯一标识响应回来时自动匹配不用手动对账Promise 风格调用call(action, params)返回 Promise配合async/await非常清爽事件订阅能力与 DCRF 的 observer 机制完美配合实时推送数据直接回调处理。这背后的协议其实很简单前端发送{action: list, request_id: 42}服务端在 consumers.py 的receive_json中取出 action 并分发到对应方法再通过reply回传{action: list, response_status: 200, request_id: 42, data: [...]}。dcrf-client 只是帮你把这些协议细节全部封装好了。进阶实战用 model_observer 实现实时推送 实时应用的核心价值在于「数据一变前端马上知道」。DCRF 的 observer 模块提供了两种订阅方式方式一订阅单个模型实例使用ObserverModelInstanceMixin客户端可以订阅某条记录的变更后续该记录的每次更新都会自动推送到前端。from djangochannelsrestframework.generics import GenericAsyncAPIConsumer from djangochannelsrestframework.mixins import ObserverModelInstanceMixin class TestConsumer(ObserverModelInstanceMixin, GenericAsyncAPIConsumer): queryset User.objects.all() serializer_class UserSerializer前端只需发送一条订阅消息await consumer.call(subscribe_instance, { pk: 42, request_id: 4 });此后该用户信息一有变动前端就会收到形如{action: update, data: {...}}的推送。方式二订阅整个模型的全部变更如果你希望「谁改了数据都通知我」可以使用model_observer装饰器源码见 model_observer.pyfrom djangochannelsrestframework.observer import model_observer class MyConsumer(GenericAsyncAPIConsumer): model_observer(User) async def user_activity(self, message, observerNone, actionNone, **kwargs): # action 可能为 create / update / delete await self.send_json(message)在websocket_connect中订阅即可async def websocket_connect(self, message): await super().websocket_connect(message) await self.user_activity.subscribe() 注意model_observer依赖 Django 的信号机制批量更新如User.objects.filter(...).update(...)不会触发通知且同一文件内若多个方法装饰了同一个模型务必使用不同的方法名。更灵活的玩法自定义 action 与权限控制 自定义 action除了内置 CRUD你还可以用action()装饰器定义在 decorators.py扩展任意业务动作from djangochannelsrestframework.decorators import action class UserConsumer(GenericAsyncAPIConsumer): action() def send_welcome_email(self, pkNone, **kwargs): # 同步方法会被自动包在 database_sync_to_async 中执行 return {status: sent}, 200 action(detachedTrue) async def long_task(self, **kwargs): # detachedTrue 时该动作不会阻塞其他消息处理 ... return {}, 200前端调用方式与其他动作完全一致consumer.call(send_welcome_email, { pk: 1 })。权限控制DCRF 的权限体系与 DRF 同名但独立实现导入路径见 permissions.pyfrom djangochannelsrestframework import permissions class UserConsumer(GenericAsyncAPIConsumer): permission_classes (permissions.IsAuthenticated,)连接建立时和每个 action 调用前都会执行权限校验未通过会直接关闭连接或返回错误码。常见坑与最佳实践清单 ✅务必使用.as_asgi()不要实例化 Consumer否则会出现莫名的并发问题同步代码注意线程安全ORM 操作在异步环境必须走database_sync_to_asyncDCRF 的action()已自动帮你处理同步方法request_id 不能省它是前端匹配响应与订阅的关键标识dcrf-client 已自动管理批量更新不触发 model_observer需要监控批量变更时请手动发送通知权限写在 Consumer 上而非序列化器每个 Consumer 的permission_classes独立生效多实例部署需配置 channel layer生产环境推荐使用 Redis channel layer否则 observer 群组消息无法跨进程传递。写在最后 通过本文的完整实战你已经掌握了 djangochannelsrestframework 的核心用法用GenericAsyncAPIConsumer Mixin 快速搭建 WebSocket API用 dcrf-client 在前端优雅地调用这些接口再用 observer 机制实现模型级实时推送。这套组合足以支撑聊天室、实时看板、协同编辑、消息通知等绝大多数实时业务场景。如果你的项目刚好需要「HTTP 之外」的实时能力不妨把 DCRF 引入技术栈它的学习曲线比想象中平缓得多——毕竟它就是 WebSocket 世界的 Django REST Framework。【免费下载链接】djangochannelsrestframeworkA Rest-framework for websockets using Django channels-v4项目地址: https://gitcode.com/gh_mirrors/dj/djangochannelsrestframework创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考