Django实战：HTTP状态码与业务状态码的分层设计与实战应用

一、HTTP 状态码

介绍

HTTP响应状态码是用以表示网页服务器HTTP响应状态的3位数字代码。它由HTTP协议定义，用于描述请求 - 响应过程中的各种状态，帮助客户端（如浏览器）理解服务器的响应结果。

打开Chrome浏览器——F12——网络，查看响应标头。

HTTP状态码五个类别

1xx: 信息性状态码

状态码	状态码英文	描述
100	Continue	服务器已经收到了请求的初始部分，客户端应该继续发送请求
101	Switching Protocols	服务器根据客户端的请求切换协议

2xx: 成功状态码

状态码	状态码英文	描述
200	OK	请求成功，通常用于 GET 请求
201	Created	请求成功，并且创建了新的资源
202	Accepted	请求已被接受处理，但处理尚未完成
204	No Content	请求成功，但没有返回任何内容
205	Reset Content	告诉客户端重置发送了请求的文档

3xx: 重定向状态码

状态码	状态码英文	描述
300	Multiple Choices	表示有多个选择，客户端可以选择其中一个
301	Moved Permanently	资源已被永久移动到新的 URL
302	Found（之前是 “Moved Temporarily”）	资源临时移动到新的 URL
303	See Other	告诉客户端在另一个 URL 上获取资源
304	Not Modified	资源未修改，可以使用缓存版本
307	Temporary Redirect	资源临时移动到新的 URL，与 302 类似，但不会改变请求方法
308	Permanent Redirect	资源已被永久移动到新的 URL，与 301 类似，但不会改变请求方法

4xx: 客户端错误状态码

状态码	状态码英文	描述
400	Bad Request	请求格式错误，服务器无法理解
401	Unauthorized	请求需要用户认证
403	Forbidden	服务器理解请求，但拒绝执行
404	Not Found	请求的资源不存在
405	Method Not Allowed	请求的 HTTP 方法不被允许
406	Not Acceptable	服务器无法生成符合客户端要求的响应
408	Request Timeout	请求超时，服务器等待了太长时间
409	Conflict	请求与服务器上的资源状态冲突
410	Gone	请求的资源已被永久删除

5xx: 服务器错误状态码

状态码	状态码英文	描述
500	Internal Server Error	服务器内部错误，无法完成请求
501	Not Implemented	服务器不支持请求的功能
502	Bad Gateway	作为网关或代理的服务器从上游服务器收到了无效的响应
503	Service Unavailable	服务器目前无法处理请求，可能是临时超载或维护
504	Gateway Timeout	作为网关或代理的服务器没有及时从上游服务器收到响应
505	HTTP Version Not Supported	服务器不支持请求的 HTTP 协议版本

参考资料：HTTP 响应状态码

二、业务状态码

介绍

业务状态码是应用层定义的状态码，用于描述具体业务逻辑的处理结果。它与HTTP状态码不同，HTTP状态码主要关注协议层面的通信状态，而业务状态码关注的是应用逻辑是否成功、失败以及失败的具体原因等。

• 自定义性：业务状态码是根据具体业务需求定义的。
• 详细性：业务状态码可以更详细地描述业务逻辑的处理结果。

区别与联系

在前后端交互中，HTTP状态码和业务状态码是两种不同的错误处理机制，它们的用途和触发方式不同：

对比项	HTTP状态码	业务状态码
定义	由HTTP协议定义的标准状态码（如200、401、404、500）	后端自定义的业务逻辑状态码（如 { code: 401, msg: "未登录" }）
触发方式	由服务器直接返回HTTP响应头（如 HTTP/1.1 401 Unauthorized）	由后端在HTTP 200响应体里返回（如 { code: 401, data: null }）
Axios拦截器处理	触发 response.interceptors 的 错误回调（error.response.status）	触发 response.interceptors 的 成功回调（response.data.code）
典型用途	表示HTTP请求本身的成功/失败（如网络错误）	表示业务逻辑的成功/失败（如余额不足、权限不足）

业务状态码示例

用户登录失败时，服务器响应数据如下：

• code：业务状态码
• data：服务器返回数据
• msg：服务器返回消息提示

{"code":111201,"data":null,"msg":"账号或密码错误"}

注意：虽然是发生业务逻辑错误，但此时的 HTTP 状态码仍然为 200

三、项目实战

一个Django+DRF的后台管理系统项目，设计并使用业务状态码，可拆分为以下步骤：

设计业务状态码

设计业务状态码分配规则

• 范围：100000 - 999999
• 第一段，2 位，表示应用APP。例如：myapp_system, myapp_infra
• 第二段，2 位，表示模块。例如：user, dept
• 第三段，2 位，表示自增数字。

业务状态码具体分配示例

一、项目框架预留
framework-exception      101100 - 101199

二、myapp_system 应用APP
system-user              111100 - 111199
system-auth              111200 - 111299
system-dept              111300 - 111399
system-post              111400 - 111499
system-role              111500 - 111599
system-menu              111600 - 111699
system-user_profile      111700 - 111799
system-notify_message    111800 - 111899
system-permission        111900 - 111999
system-dict_type         112000 - 112099
system-captcha           112100 - 112199

三、myapp_infra 应用APP
infra-job               121100 - 121199
infra-file_config       121200 - 121299
infra-file              121300 - 121399
infra-config            121400 - 121499

设计全局响应格式

封装DRF的Response类，定义通用响应工具类

from rest_framework.response import Response
from rest_framework import status

class CommonResponse:
    """通用响应工具类"""

    @staticmethod
    def success(code=0, data=True, msg="", status_code=status.HTTP_200_OK):
        """业务成功响应"""
        return Response(
            {
                "code": code,  # 业务状态码为 0 表示成功
                "data": data,
                "msg": msg,
            },
            status=status_code,  # HTTP 状态码默认为200
        )

    @staticmethod
    def error(code=500, data=None, msg="Error", status_code=status.HTTP_200_OK):
        """业务错误响应，配合业务状态码使用"""
        return Response(
            {
                "code": code,
                "data": data,
                "msg": msg,
            },
            status=status_code,
        )

业务状态码实战

实战场景：用户登录过程中，可能出现账号或密码错误、用户已停用等情形。此时需要用到业务状态码进行友好提示。如下图所示：

代码实现效果：当账号或密码错误

代码实现效果：当用户已停用

代码实现效果：当登录成功

点击查看完整代码

---

您正在阅读的是《Django从入门到实战》专栏！关注不迷路~