HTTP 状态码工具函数文档

HTTP 状态码工具函数文档

概述

本文档介绍一个基于 TypeScript 的 HTTP 状态码工具函数库，提供状态码消息获取、类型判断、UI 集成等功能，覆盖全量标准 HTTP 状态码，确保类型安全与企业级应用可靠性。

核心类型与常量

1.HttpStatusCode类型

功能：定义支持的 HTTP 状态码集合，确保类型校验。

包含范围：1xx（信息响应）、2xx（成功响应）、3xx（重定向）、4xx（客户端错误）、5xx（服务器错误）全量标准状态码。

export type HttpStatusCode =

| 100 | 101 | 102 | 103

| 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 226

| 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308

| 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410

| 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423

| 424 | 425 | 426 | 428 | 429 | 431 | 451

| 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 509 | 510 | 511;

2.HTTP_STATUS_MESSAGES常量

功能：存储状态码与描述消息的映射关系，支持多语言友好的详细说明。

结构：按状态码类别分组（1xx-5xx），每个状态码对应准确的语义描述。

export const HTTP_STATUS_MESSAGES: Record<HttpStatusCode, string> = {

// 信息响应 (1xx)

100: '继续。客户端应继续其请求',

101: '切换协议。服务器根据客户端的请求切换协议',

// ... 2xx/3xx/4xx/5xx 状态码映射（完整覆盖所有 HttpStatusCode 类型）

404: '请求的资源不存在',

500: '服务器内部错误',

418: '我是一个茶壶。超文本咖啡壶控制协议，愚人节笑话', // 特殊状态码示例

};

主要工具函数

1.getHttpMessage

功能：根据 HTTP 状态码获取对应的描述消息。

参数：statusCode: number- HTTP 状态码

返回值：string- 状态码描述消息（未知状态码返回未知状态码: ${statusCode}）

export const getHttpMessage = (statusCode: number): string => {

return HTTP_STATUS_MESSAGES[statusCode as HttpStatusCode] || `未知状态码: ${statusCode}`;

};

2. 错误状态判断函数

函数名	功能描述	参数	返回值
isErrorStatusCode	判断是否为错误状态码（4xx/5xx）	statusCode: number	boolean
isClientError	判断是否为客户端错误（4xx）	statusCode: number	boolean
isServerError	判断是否为服务器错误（5xx）	statusCode: number	boolean

代码示例：

export const isErrorStatusCode = (statusCode: number): boolean => {

return statusCode >= 400 && statusCode < 600;

};

export const isClientError = (statusCode: number): boolean => {

return statusCode >= 400 && statusCode < 500;

};

export const isServerError = (statusCode: number): boolean => {

return statusCode >= 500 && statusCode < 600;

};

3. 状态码分类与属性函数

函数名	功能描述	返回值类型
getStatusCodeCategory	获取状态码类别（如“成功响应”）	string（信息响应/成功响应/重定向/客户端错误/服务器错误/未知）
getStatusCodeSeverity	获取严重程度	'info' \| 'warning' \| 'error'
getStatusCodeColorClass	获取UI颜色类名（适配Quasar）	string（如text-info/text-negative）
getStatusCodeIcon	获取UI图标名称（适配Quasar）	string（如info/error）

代码示例：

export const getStatusCodeCategory = (statusCode: number): string => {

if (statusCode >= 100 && statusCode < 200) return '信息响应';

if (statusCode >= 200 && statusCode < 300) return '成功响应';

// ... 其他类别判断逻辑

};

组件集成示例

以错误对话框组件为例，展示如何结合工具函数实现状态码相关的动态UI展示：

// 错误对话框组件中导入工具函数

import {

getHttpMessage,

getStatusCodeCategory,

getStatusCodeSeverity,

getStatusCodeColorClass,

getStatusCodeIcon

} from '@/utils/httpMessages';

// 组件内计算属性（基于Vue3 Composition API示例）

const displayMessage = computed(() => {

return props.errorMessage || getHttpMessage(props.errorCode); // 优先使用自定义消息，否则自动获取

});

const statusCategory = computed(() => getStatusCodeCategory(props.errorCode));

const statusSeverity = computed(() => getStatusCodeSeverity(props.errorCode));

const statusColorClass = computed(() => getStatusCodeColorClass(props.errorCode));

const statusIcon = computed(() => getStatusCodeIcon(props.errorCode));

UI渲染示例（模板伪代码）：

<template>

<q-dialog>

<q-card>

<q-card-section>

<q-icon :name="statusIcon" :class="statusColorClass" size="lg" />

<h5>{{ statusCategory }} ({{ props.errorCode }})</h5>

<p>{{ displayMessage }}</p>

</q-card-section>

</q-card>

</q-dialog>

</template>

使用示例

基础用法

// 获取状态码消息

console.log(getHttpMessage(200)); // "请求成功"

console.log(getHttpMessage(404)); // "请求的资源不存在"

console.log(getHttpMessage(418)); // "我是一个茶壶。超文本咖啡壶控制协议，愚人节笑话"

// 判断错误类型

console.log(isErrorStatusCode(200)); // false（成功响应）

console.log(isErrorStatusCode(503)); // true（服务器错误）

console.log(isClientError(403)); // true（客户端错误）

API错误处理场景

// 接口请求错误处理逻辑

const handleApiError = (error: any) => {

if (error.response) {

const { status: statusCode, data } = error.response;

const message = getHttpMessage(statusCode); // 自动匹配状态码消息

// 结合严重程度处理不同错误

if (getStatusCodeSeverity(statusCode) === 'error') {

reportCriticalError(statusCode, message, data); // 严重错误上报

}

// 显示错误对话框

showErrorDialog({

code: statusCode,

message,

details: data,

severity: getStatusCodeSeverity(statusCode),

});

}

};

设计特点

1. 完整覆盖：支持所有标准 HTTP 状态码（1xx-5xx），包含特殊状态码（如418“茶壶”）。

2. 类型安全：基于 TypeScript 类型系统，确保状态码参数与返回值的类型一致性，减少运行时错误。

3. 企业级功能：提供错误分类、严重程度判断、UI适配（颜色/图标）等工程化能力，满足复杂应用需求。

4. 语义化描述：每个状态码消息遵循 RFC 规范，准确反映 HTTP 标准语义，避免歧义。

5. 模块化设计：函数职责单一，支持按需导入（如仅使用getHttpMessage或错误判断函数）。

6. UI框架兼容：内置与 Quasar 等UI框架集成的辅助函数（getStatusCodeColorClass/getStatusCodeIcon），降低前端开发成本。

7. 可扩展性：通过HTTP_STATUS_MESSAGES常量统一管理消息，支持多语言扩展或自定义描述。

总结

该工具函数库为 HTTP 状态码处理提供了一站式解决方案，从基础的消息获取到高级的错误分类与UI集成，兼顾了类型安全、易用性和工程化需求，可直接用于企业级前端项目的错误处理模块。