@hxsy/aihpapi

从 api_config.json 读取 OpenAPI 文档并生成 TypeScript 类型包，主要用于业务代码和 AI 快速查询后端接口、入参、出参和 schema。

Generate

pnpm --filter @hxsy/aihpapi run generate

生成结果在 types/ 目录，npm 包入口为 types/index.d.ts。

Import

推荐从包根入口导入服务命名空间：

import type { followup, hyos } from "@hxsy/aihpapi";

也可以按微服务子路径导入完整导出项：

import type { Path, Request, Response } from "@hxsy/aihpapi/hyos";

Exports

Root Exports

根入口 @hxsy/aihpapi 按微服务导出 namespace。

| Export | 说明 | | --- | --- | | followup | followup 微服务的类型命名空间。 | | hyos | hyos 微服务的类型命名空间。 |

每个服务命名空间都会导出该服务的工具类型和所有后端 schema 类型。例如：

import type { hyos } from "@hxsy/aihpapi";

type AllHyosPaths = hyos.Path;
type PageReq = hyos.HxPageRequestEventTypeQueryReqVO;
type PageRes = hyos.BaseResponseEventTypePageQueryResVO;

根入口的服务命名空间包含这些 export：

| Export | 说明 | | --- | --- | | Path | 当前服务所有接口 path 的联合类型。 | | paths | Path 的别名。 | | Method<P> | 指定 path 后可用 method 的联合类型。 | | Operation<P, M> | 指定 path 和 method 后的接口元信息。 | | RequestOptions<P, M> | 指定 path 和 method 后自动推导出的 request options 类型。 | | Request<P, M> | RequestOptions<P, M> 的别名。 | | Response<P, M> | 指定 path 和 method 后自动推导出的 response 类型。 | | RequestFunction | 可用于约束业务 request 函数的泛型函数签名。 | | 后端 schema 类型 | 所有 components.schemas 对应的 schema 类型。 |

Service Exports

子路径 @hxsy/aihpapi/{service} 会导出该服务的全部类型。

| Export | 说明 | | --- | --- | | HttpMethod | OpenAPI HTTP method 联合类型，例如 "get" | "post" | "put" | ...。 | | OperationMap | 完整接口映射表，key 是 path，value 是该 path 下所有 method 的接口元信息。 | | Path | 当前服务所有接口 path 的联合类型。 | | paths | Path 的别名，适合 hyos.paths 这种更自然的读取方式。 | | Method<P> | 指定 path 后可用 method 的联合类型。 | | Operation<P, M> | 指定 path 和 method 后的接口元信息。 | | RequestOptions<P, M> | 指定 path 和 method 后自动推导出的 request options 类型。 | | Request<P, M> | RequestOptions<P, M> 的别名。 | | Response<P, M> | 指定 path 和 method 后自动推导出的 response 类型。 | | RequestFunction | 可用于约束业务 request 函数的泛型函数签名。 | | defineRequest | 类型推导示例函数声明，只用于类型检查，不提供运行时实现。 | | 后端 schema 类型 | 所有 components.schemas 会按后端名称导出，例如 BaseResponseEventTypePageQueryResVO。 |

Utility Types

HttpMethod

表示 OpenAPI 支持的 HTTP method。

import type { HttpMethod } from "@hxsy/aihpapi/hyos";

const method: HttpMethod = "post";

OperationMap

完整接口映射。一般业务代码不直接使用它，适合 AI 或工具代码枚举接口。

import type { OperationMap } from "@hxsy/aihpapi/hyos";

type EventTypeCreate = OperationMap["/admin/event-type/create"]["post"];
type EventTypeCreateBody = EventTypeCreate["body"];
type EventTypeCreateResponse = EventTypeCreate["response"];

OperationMap 中每个接口包含：

| 字段 | 说明 | | --- | --- | | path | 当前接口 path 字面量。 | | method | 当前接口 method 字面量。 | | params | path 参数，例如 /user/{id} 中的 id。无参数时为 {}。 | | query | query 参数。无参数时为 {}。 | | queryRequired | 是否存在必填 query 参数。 | | headers | header 参数。无参数时为 {}。 | | headersRequired | 是否存在必填 header 参数。 | | body | request body 类型。无 body 时为 never。 | | bodyRequired | body 是否必填。 | | response | 成功响应类型，优先取 200/201/202/203/204/206。 |

Path 和 paths

Path 是某个服务所有接口 path 的联合类型。paths 是别名，用法相同。

import type { hyos } from "@hxsy/aihpapi";

type HyosPath = hyos.Path;
type HyosPaths = hyos.paths;

const path: HyosPath = "/admin/event-type/page-query";

Method<P>

指定 path 后，只允许使用该 path 实际存在的 method。

import type { hyos } from "@hxsy/aihpapi";

type PageQueryMethod = hyos.Method<"/admin/event-type/page-query">;

const method: PageQueryMethod = "post";

如果写了该 path 不支持的 method，TypeScript 会报错。

import type { hyos } from "@hxsy/aihpapi";

// @ts-expect-error: 该接口没有 get method。
const method: hyos.Method<"/admin/event-type/page-query"> = "get";

Operation<P, M>

获取单个接口的完整元信息。

import type { hyos } from "@hxsy/aihpapi";

type Op = hyos.Operation<"/admin/event-type/page-query", "post">;
type Body = Op["body"];
type Res = Op["response"];

RequestOptions<P, M>

根据 path 和 method 自动组合 params、query、headers、body。

import type { hyos } from "@hxsy/aihpapi";

type Options = hyos.RequestOptions<"/admin/event-type/page-query", "post">;

const options: Options = {
  body: {
    pageNo: 1,
    pageSize: 10,
  },
};

生成规则：

| OpenAPI 内容 | RequestOptions 表现 | | --- | --- | | 有 path 参数 | 生成必填 params。 | | 无 path 参数 | 不生成 params 要求。 | | 有必填 query 参数 | 生成必填 query。 | | 只有可选 query 参数 | 生成可选 query?。 | | 无 query 参数 | 不生成 query 要求。 | | 有必填 header 参数 | 生成必填 headers。 | | 只有可选 header 参数 | 生成可选 headers?。 | | 有必填 body | 生成必填 body。 | | 有可选 body | 生成可选 body?。 | | 无 body | 不生成 body 要求。 |

Request<P, M>

Request<P, M> 是 RequestOptions<P, M> 的别名，便于写更短的业务类型。

import type { hyos } from "@hxsy/aihpapi";

type PageQueryReq = hyos.Request<"/admin/event-type/page-query", "post">;

Response<P, M>

获取某个接口成功响应类型。

import type { hyos } from "@hxsy/aihpapi";

type PageQueryRes = hyos.Response<"/admin/event-type/page-query", "post">;

RequestFunction

用于约束业务项目里的 request 函数，让 path、method、options 和返回值自动联动。

import type { hyos } from "@hxsy/aihpapi";

export const hyosReq: hyos.RequestFunction = async (path, method, options) => {
  const response = await request({
    url: path,
    method,
    params: "query" in options ? options.query : undefined,
    data: "body" in options ? options.body : undefined,
  });

  return response.data;
};

const result = await hyosReq("/admin/event-type/page-query", "post", {
  body: {
    pageNo: 1,
    pageSize: 10,
  },
});

defineRequest

defineRequest 是 paths.d.ts 中导出的声明函数，只用于类型推导示例，没有运行时实现。

不要在运行时代码中调用它。需要做类型测试时，可以只读取它的类型：

type DefineHyosRequest = typeof import("@hxsy/aihpapi/hyos").defineRequest;
type DefineHyosRequestParams = Parameters<DefineHyosRequest>;
type DefineHyosRequestResult = ReturnType<DefineHyosRequest>;

如果要验证某个调用是否满足类型约束，应在不会产出运行时代码的类型测试文件中使用：

declare const defineHyosRequest: typeof import("@hxsy/aihpapi/hyos").defineRequest;

defineHyosRequest("/admin/event-type/page-query", "post", {
  body: {
    pageNo: 1,
    pageSize: 10,
  },
});

推荐业务项目自己实现 request，然后使用 RequestFunction 约束它。

Schema Types

所有后端 components.schemas 都会作为 type export 输出，命名尽量保持与后端一致。

根入口使用方式：

import type { hyos } from "@hxsy/aihpapi";

type ReqVO = hyos.EventTypeCreateReqVO;
type ResVO = hyos.BaseResponseEventTypeCreateResVO;

服务子路径使用方式：

import type {
  EventTypeCreateReqVO,
  BaseResponseEventTypeCreateResVO,
} from "@hxsy/aihpapi/hyos";

如果后端 schema 名称是合法 TypeScript 标识符，会原样导出，包括中文 schema 名称：

import type { followup } from "@hxsy/aihpapi";

type RiskReq = followup.患者风险评估信息请求VO;
type RiskRes = followup.BaseResponseList患者风险评估信息响应VO;

如果后端 schema 名称不是合法 TypeScript 标识符，生成脚本会转换为合法 type 名，并在生成文件的注释中保留原始 schema 名称。

Request Examples

获取 path 列表类型

import type { hyos } from "@hxsy/aihpapi";

function useHyosPath(path: hyos.Path) {
  return path;
}

useHyosPath("/admin/event-type/create");

根据 path 推导 method

import type { hyos } from "@hxsy/aihpapi";

function useMethod<P extends hyos.Path>(path: P, method: hyos.Method<P>) {
  return { path, method };
}

useMethod("/admin/event-type/create", "post");

根据 path 和 method 推导入参

import type { hyos } from "@hxsy/aihpapi";

function buildOptions<P extends hyos.Path, M extends hyos.Method<P>>(
  path: P,
  method: M,
  options: hyos.Request<P, M>,
) {
  return { path, method, options };
}

buildOptions("/admin/event-type/page-query", "post", {
  body: {
    pageNo: 1,
    pageSize: 10,
  },
});

根据 path 和 method 推导返回值

import type { hyos } from "@hxsy/aihpapi";

async function pageQuery(): Promise<hyos.Response<"/admin/event-type/page-query", "post">> {
  return hyosReq("/admin/event-type/page-query", "post", {
    body: {
      pageNo: 1,
      pageSize: 10,
    },
  });
}

封装某个微服务 request

import type { hyos } from "@hxsy/aihpapi";

export const hyosReq: hyos.RequestFunction = async (path, method, options) => {
  const response = await request({
    baseURL: "/hyos",
    url: path,
    method,
    params: "query" in options ? options.query : undefined,
    data: "body" in options ? options.body : undefined,
  });

  return response.data;
};

同时封装多个微服务 request

import type { followup, hyos } from "@hxsy/aihpapi";

export const hyosReq: hyos.RequestFunction = async (path, method, options) => {
  const response = await request({
    baseURL: "/hyos",
    url: path,
    method,
    params: "query" in options ? options.query : undefined,
    data: "body" in options ? options.body : undefined,
    headers: "headers" in options ? options.headers : undefined,
  });

  return response.data;
};

export const followupReq: followup.RequestFunction = async (path, method, options) => {
  const response = await request({
    baseURL: "/followup",
    url: path,
    method,
    params: "query" in options ? options.query : undefined,
    data: "body" in options ? options.body : undefined,
    headers: "headers" in options ? options.headers : undefined,
  });

  return response.data;
};

For AI

AI 写业务代码时优先查看这些文件：

| 文件 | 用途 | | --- | --- | | types/index.d.ts | 查看有哪些微服务 namespace，以及每个服务导出的 schema。 | | types/{service}/paths.d.ts | 查看接口 path、method、入参和返回值。 | | types/{service}/schemas.d.ts | 查看后端 schema 结构。 |

推荐 AI 先通过 Path 或 paths 确认接口是否存在，再通过 Request<P, M> 和 Response<P, M> 获取接口出入参，避免手写不存在的 path、字段或返回结构。