HTTP 传输与响应信封

GStableHttp、DEFAULT_BASE_URL、DEFAULT_PUBLIC_BASE_URL、HttpMethod、GStableHttpOptions 以及类型 ApiEnvelope 均由 gstable-js 导出（src/http.ts、src/types/common.ts；见 src/index.ts）。

---

GStableHttp 构造函数

构建知晓私有/公开 base URL 并会对私有请求签名的底层客户端。除非需要 AiPaymentResource 或自定义路径，否则优先使用 GStableClient。

new GStableHttp(options)

参数

选项对象 GStableHttpOptions（与 GStableClient 使用相同字段）：

字段	类型	必填	说明
apiKey	string	是	已 trim；除已带前缀外会加上 Bearer 。
baseUrl	string	否	私有 API 根；默认 DEFAULT_BASE_URL。
publicBaseUrl	string	否	公开 API 根；默认 DEFAULT_PUBLIC_BASE_URL。
fetchImpl	typeof fetch	否	覆盖 fetch（测试/自定义运行时）。

示例

import { GStableHttp } from 'gstable-js';

const http = new GStableHttp({
  apiKey: process.env.GSTABLE_API_KEY!,
});

---

requestJson

对配置的 私有 base URL 执行已鉴权的 GET 或 POST。

http.requestJson(method, path, body?)

签名（概念上）

requestJson<T>(method: 'GET' | 'POST', path: string, body?: unknown): Promise<T>

参数

名称	类型	必填	说明
method	HttpMethod ('GET' | 'POST')	是	GStable API 使用的动词。
path	string	是	相对私有 base URL 的路径；可有或可无前导 /。
body	unknown	否	POST 时在非 undefined 下 JSON 序列化；GET 忽略 body。

自动设置的请求头

• Accept: application/json
• Content-Type: application/json
• Authorization：Bearer + 你的 API key

返回值

Promise<T> — 当 HTTP 成功且 code === 0 时，返回 API 信封中的 data。

示例

import { GStableHttp } from 'gstable-js';

const http = new GStableHttp({ apiKey: process.env.GSTABLE_API_KEY! });
type MyDto = { ok: boolean };
const path: string = '...'; // 仅进阶用法 — 优先使用 Resource 方法
const data = await http.requestJson<MyDto>('GET', path);

---

requestPublicJson

对 公开 base URL 执行 GET 或 POST，不带 Authorization。

http.requestPublicJson(method, path, body?)

签名（概念上）

requestPublicJson<T>(method: 'GET' | 'POST', path: string, body?: unknown): Promise<T>

参数

与 requestJson 的 method、path、body 相同。

请求头

• 仅 Accept、Content-Type — 无 bearer token。

返回值

成功时返回解包后的 data。

示例

应用代码中优先使用 client.capability.all()，而非直接调用 requestPublicJson。

---

响应处理

API 返回兼容 ApiEnvelope 的信封（泛型 data 载荷；见 src/types/common.ts）包含 code、message、data。SDK 行为：

1. 读取响应文本并解析 JSON。
2. 校验存在数字型 code。
3. 若 HTTP 错误或 JSON 无效/非信封 → GStableError（对 401/403/非 JSON 等常带提示）。
4. 若 code !== 0 → createTypedApiError → GStableProductError | GStableCommonError | GStablePlatformError | GStableError。
5. 成功 → 仅返回 data。

信封形状见 API 简介。

网络错误

在收到任何 HTTP 响应之前的失败使用 code: -1 与 Network error: …。

下一步

• 错误码与 SDK 异常