@evertro/http-utils

HTTP 通用常量与统一响应体工具包（TypeScript）。

对应 Java 版 com.wy.ai.constant.CommonConstant 和 com.wy.ai.dto.ResponseDto<T>。

安装

npm install @evertro/http-utils

快速开始

import { ResponseDto, SUCCESS_CODE, HEADER_AUTH } from "@evertro/http-utils";

API 文档

常量

认证 & 授权

| 常量名 | 类型 | 值 | 说明 | |---|---|---|---| | JWT_MAX_AGE_MINUTES | number | 525600 | JWT 最大有效期（分钟），365 天 | | JWT_ONE_STEP_MINUTES | number | 30 | JWT 单步有效期（分钟） | | TOKEN_COOKIE_NAME | string | "jwt-token" | 存储 JWT 的 Cookie 名称 |

错误码

| 常量名 | 值 | 说明 | |---|---|---| | SUCCESS_CODE | "00000" | 成功码 | | BIP_SUCCESS_CODE | "1000000000" | BIP 成功码 | | DEFAULT_SYS_ERROR_CODE | "00099" | 默认系统错误码 | | DEFAULT_LOGOUT_ERROR_CODE | "00401" | 默认登出错误码 | | DEFAULT_FORBIDDEN_ERROR_CODE | "00403" | 默认禁止访问错误码 | | DEFAULT_SYS_ERROR_MSG | "系统内部错误" | 默认系统错误消息 |

HTTP Header 键名

| 常量名 | 值 | 说明 | |---|---|---| | HEADER_AUTH | "Authorization" | 认证头 | | HEADER_SAAS_AUTH | "extendFields" | SaaS 认证头 | | HEADER_FRONT_TYPE | "Fronttype" | 前端类型头 | | LOGIN_VALID_SECOND | 86400 | 登录有效期（秒） |

Feign 内部调用 Header

| 常量名 | 值 | |---|---| | FEIGN_HEADER_TRACE_ID | "FEIGN_TRACE_ID" | | FEIGN_HEADER_USER_ID | "FEIGN_USER_ID" | | FEIGN_HEADER_USER_NAME | "FEIGN_USER_NAME" | | FEIGN_HEADER_USER_TYPE | "FEIGN_USER_TYPE" | | FEIGN_HEADER_FRONT_TYPE | "FEIGN_FRONT_TYPE" | | FEIGN_HEADER_IP | "FEIGN_IP" | | FEIGN_HEADER_ROLE_TYPE | "ROLE_TYPE" | | FEIGN_HEADER_ROLE_IDS | "ROLE_IDS" | | FEIGN_HEADER_USER_CODE | "USER_CODE" | | FEIGN_HEADER_PLAT_FORM | "Platform" | | FEIGN_HEADER_DEVICE_ID | "Deviceid" | | FEIGN_HEADER_SAAS_TOKEN | "SAAS_TOKEN" |

其他

| 常量名 | 值 | 说明 | |---|---|---| | DEFAULT_COURT_UUID | "00000000000000000000000000000000" | 默认法院 UUID |

ResponseDto<T>

统一响应体泛型类，结构为 { code, data, message }。

属性

| 属性 | 类型 | 说明 | |---|---|---| | code | string | 响应码 | | data | T \| null | 响应数据 | | message | string | 响应消息 |

构造函数

new ResponseDto<T>(options?: ResponseDtoOptions<T>)

interface ResponseDtoOptions<T> {
  code?: string;
  data?: T | null;
  message?: string;
}

示例：

const resp = new ResponseDto({
  code: "00000",
  data: { id: 1, name: "张三" },
  message: "操作成功",
});

静态工厂方法

ResponseDto.success<T>(data: T, message?: string): ResponseDto<T>

创建成功响应，自动填充 SUCCESS_CODE（"00000"）。

const resp = ResponseDto.success({ id: 1, name: "张三" });
// { code: "00000", data: { id: 1, name: "张三" }, message: "操作成功" }

const resp2 = ResponseDto.success([1, 2, 3], "查询成功");
// { code: "00000", data: [1, 2, 3], message: "查询成功" }

ResponseDto.error(code: string, message: string): ResponseDto<null>

创建错误响应，data 为 null。

const resp = ResponseDto.error("10001", "参数校验失败");
// { code: "10001", data: null, message: "参数校验失败" }

ResponseDto.systemError(message?: string): ResponseDto<null>

创建系统错误响应，使用 DEFAULT_SYS_ERROR_CODE（"00099"）。

const resp = ResponseDto.systemError();
// { code: "00099", data: null, message: "系统内部错误" }

const resp2 = ResponseDto.systemError("数据库连接超时");
// { code: "00099", data: null, message: "数据库连接超时" }

实例方法

getCode(): string

获取 code，null 安全并自动 trim。与 Java 版 getCode() 行为一致。

resp.getCode(); // "00000"

isSuccess(): boolean

判断响应是否成功（code trim 后等于 SUCCESS_CODE）。

const resp = ResponseDto.success("ok");
resp.isSuccess(); // true

const err = ResponseDto.error("10001", "失败");
err.isSuccess(); // false

toString(): string

格式化输出。

resp.toString();
// "ResponseDto [code=00000, data=ok, message=操作成功]"

兼容性

同时支持 ESM 和 CommonJS：

// ESM
import { ResponseDto } from "@evertro/http-utils";

// CommonJS
const { ResponseDto } = require("@evertro/http-utils");

完整的 TypeScript 类型声明（.d.ts）随包发布，支持泛型类型推断。

构建

npm run build    # 构建 ESM + CJS + DTS
npm run clean    # 清理构建产物

License

MIT