API 客户端

从已提交的 OpenAPI 和错误合约中使用 Lenso HTTP API。

使用承诺的合约作为事实来源。不要推断请求或响应 旧示例中的形态。

合约文件

如果代理正在编写集成，则通过 lenso-api-client 路由它 技能：

npx skills add lenso-dev/skills

然后询问确切的合约路径、端点、方法、请求形式、响应 形态，以及一个重点验证命令。

最小获取助手

使用您的应用程序已经喜欢的生成的客户端。对于小额检查或示例， 简单的 fetch 就足够了：

type LensoErrorResponse = {
  error: {
    code: string;
    message: string;
    request_id: string | null;
    correlation_id: string | null;
    details: Array<{ field: string | null; reason: string }>;
  };
};

export async function lensoFetch<T>(
  input: RequestInfo | URL,
  init?: RequestInit,
): Promise<T> {
  const response = await fetch(input, {
    ...init,
    headers: {
      accept: "application/json",
      ...init?.headers,
    },
  });

  const body = await response.json();
  if (response.ok) {
    return body as T;
  }

  const error = body as LensoErrorResponse;
  throw Object.assign(new Error(error.error.message), {
    status: response.status,
    code: error.error.code,
    requestId: error.error.request_id,
    correlationId: error.error.correlation_id,
    details: error.error.details,
  });
}

例子：

type AdminModulesResponse = {
  modules: Array<{
    name: string;
    status: string;
  }>;
};

const modules = await lensoFetch<AdminModulesResponse>(
  "http://127.0.0.1:3000/api/admin/modules",
  {
    headers: {
      authorization: `Bearer ${process.env.LENSO_SESSION_TOKEN}`,
    },
  },
);

误差包络线

每个 API 错误都使用相同的信封：

{
  "error": {
    "code": "validation_failed",
    "message": "Request body is invalid",
    "request_id": "req_123",
    "correlation_id": "corr_123",
    "details": [
      {
        "field": "title",
        "reason": "required"
      }
    ]
  }
}

x-lenso-error-code响应头携带相同的稳定错误代码。 当不解析正文时，将其用于轻量级日志记录或网关指标 需要。

常用代码

客户规则

• 从 contracts/openapi/app-api.v1.yaml 生成客户端。
• 保持生成的代码不受手动编辑。
• 在共享客户端包装器中处理一次标准错误信封。
• 记录失败时的 request_id 和 correlation_id。
• 后端 DTO 或路由更改后重新生成合约。

检查

后端API更改后：

just generate
just generated-check
just check

对于吸烟消费者来说：

curl -sS http://127.0.0.1:3000/readyz | jq .
curl -sS http://127.0.0.1:3000/api/admin/modules \
  -H "authorization: Bearer $LENSO_SESSION_TOKEN" | jq .