# @archastro/sdk-generator 中文文档 规范地址：https://npmcn.com/package/%40archastro/sdk-generator/ 版本：0\.11\.17 npm 元数据更新时间：2026-11-03T20:20:25.022Z 中文译文更新时间：2026-11-06T14:18:06.796Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40archastro/sdk-generator 原文对照：https://npmcn.com/package/%40archastro/sdk-generator/?lang=original 项目主页：https://github.com/ArchAstro/archastro-openapi#readme 源码仓库：https://github.com/ArchAstro/archastro-openapi ## 关键信息（来自 npm 元数据） - 包体积（解压后）：1.6 MB，290 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - Node.js 要求：\>=20 - 运行依赖：3 个 - 首次发布：2026-04-17T20:46:44.475Z - 最新版本发布：2026-11-03T20:20:24.640Z - 近 30 天下载量：78984（2026-10-07 至 2026-11-05，npm 官方下载统计） - 已发布版本数：42（近 12 个月 42 个） ## 中文简介 从 OpenAPI 光谱中生成打入的 TypeScript, Python, Swift, Go, Elixir, 和 Rust SDKs(+合同测试). ## 安装 ```sh npm install @archastro/sdk-generator ``` 也可以使用：`pnpm add @archastro/sdk-generator`、`yarn add @archastro/sdk-generator`、`bun add @archastro/sdk-generator` ## README # @ archastro/ sdk- 生成器 生成已键入的 TypeScript, Python, Swift, Go, Elixir, 和 Rust SDKs —— 加上跨语言 合同测试——取自ArchAstro API DSL生产的OpenAPI光谱. ## 安装 ```bash # ad-hoc npx @archastro/sdk-generator --spec ./openapi.json --lang typescript --out ./sdk # global npm install -g @archastro/sdk-generator sdk-generator --spec ./openapi.json --lang python --out ./sdk ``` ## 国 际 ``` sdk-generator --spec \ [--lang typescript|python|swift|go|elixir|rust|contract-tests-ts|contract-tests-py|contract-tests-swift|contract-tests-go|contract-tests-elixir|contract-tests-rust] \ [--out ] \ [--config ] \ [--ast-only] ``` 目标: | `--lang` | 输出 | | --- | --- | | `typescript` | TS SDK: 资源, 频道类, 认证, 客户端, Zod 计划 | | `python` | Python SDK: Pydantic 模型,资源,频道 | | `swift` | SWift SDK:可编码模型,资源,频道,同源客户端 | | `go` | Go SDK: JSON 标记的构造,上下文资源,频道,客户端 | | `elixir` | Elixir SDK:结构、资源模块、认证和凤凰频道外观 | | `rust` | Rust SDK: serde 模型, async/ blocking 资源, 键入 SSE, 认证和信道外观 | | `contract-tests-ts` | 驱动的TS合同测试 `@archastro/channel-harness` | | `contract-tests-py` | Python 合同测试( pytest + Prism 模拟服务器) | | `contract-tests-swift` | 快速合同测试(swift-testing + Prism + habel) | | `contract-tests-go` | 合同测试(`go test` +棱镜+取用) | | `contract-tests-elixir` | Elixir合同测试(Ex Unit + Prism + 牵引) | | `contract-tests-rust` | Rust 整合合同(`cargo test` +棱镜+取用) | ### 去目标配置 去解析类型 _财务报告和审定财务报表_ 从一个软件包级命名空间的函数,及其 每个目录编译一个软件包,所以 Go后端需要软件包名称 和导入路径呼叫者到达它。 两者都生活在配置文件下面 `go`数字 : ```jsonc { "go": { "packageName": "platform", "importPath": "github.com/ArchAstro/archastro-go/platform" } } ``` SDK平地着陆 `//` (单位:千美元)`types_*.go`, (中文(简体) ), `v1_*.go`, (中文(简体) ), `channels_*.go`, (中文(简体) ), `client.go`, (中文(简体) ), `auth.go`合同测试 `/contracttests/`,通过这条路径导入 SDK 。 发射器 写入结构正确 Go, 而不是列对齐 Go —— 运行 `gofmt -w` 结束 输出作为再生的一部分. ## 生成的 SDK 文档 生成器将 OpenAPI 文档保存为平面源文件 语言。 使用标准 OpenAPI 字段作为真理的来源 : - 运行 `summary` 财务报告和审定财务报表 `description` 成为 TypeScript JSDoc, Python 方法剂量弦,和斯威夫特/去 `//` 文件评论. - 参数和请求体字段 `description` 值成为参数 和输入对象字段文件. - 成功响应描述成为了返回值文件. - 司马 `description` 值变为 TypeScript 接口/schema docs 并 Python模型多克弦. - Schema 属性 `description` 值变为 TypeScript 字段 Docs, Zod `.describe(...)` 元数据,和 Pydantic `Field(description=...)` 元数据. 对于消耗 SDK repos , 将 Docs 生成保留在生成的软件包旁边 : - 类型脚本:添加类型Doc, 点 `entryPoints` 在公众生成的条目 点,并公布生成的 `docs/` 有 GitHub 页面的目录. - Python: 添加 pdoc, 将其指向生成的软件包, 并发布渲染的 带有 GitHub Pages 的 HTML . - 在 SDK 重生失败后运行 CI 中的文件构建 在释放前. ### `--config` 两个后端所消耗的共享编码元数据 : ```json { "name": "@archastro/platform-sdk", "version": "0.1.0", "baseUrl": "https://platform.archastro.ai", "apiBase": "/api", "defaultVersion": "v1", "description": "ArchAstro Platform API SDK" } ``` ### TypeScript 客户端扩展 已生成 `PlatformClient` 类 显示类型 类表达式混合接合 : ```ts const RealtimePlatformClient = PlatformClient.extend( withCustomObjectSubscriptions, ); const client = RealtimePlatformClient.withToken("pk_live_...", accessToken); ``` `extend` 返回子类而不是修改 `PlatformClient`扩展 因此,保留所生成的资源,可以连锁,并由 制造出静态工厂。 手持扩展使用标准 TypeScript 混入形状 : ```ts const withDiagnostics = (Base: TBase) => class extends Base { diagnosticLabel() { return "ready"; } }; ``` 消费SDK可以使这些模块在整个再生过程中保持公开,而无需 向发电机传授方法: ```jsonc { "typescript": { "clientExtensionModules": ["./custom-object-subscriptions.js"] } } ``` 每个已配置的模块作为 `export *` 生成的条目 包装桶。 模块本身仍然手持. ## 程序使用 ```ts import { parseOpenApiSpec, generateTypeScript, generatePython, generateContractTests, } from "@archastro/sdk-generator"; const spec = JSON.parse(readFileSync("openapi.json", "utf-8")); const ast = parseOpenApiSpec(spec, { name: "@archastro/platform-sdk" }); const files = generateTypeScript(ast, { outDir: "./sdk" }); ``` ## 发展 这个包裹住在 [`archastro-openapi`](https://github.com/archastro/archastro-openapi) 工作空间。 见根 README 构建 / 测试 / 发布指令 . ## 常见问题 ### @archastro/sdk-generator 是什么？ 从 OpenAPI 光谱中生成打入的 TypeScript, Python, Swift, Go, Elixir, 和 Rust SDKs\(\+合同测试\)\. ### 如何安装 @archastro/sdk-generator？ 在项目目录运行 npm install @archastro/sdk-generator，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 sdk-generator，可以用 npx sdk-generator 直接运行。 ### @archastro/sdk-generator 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @archastro/sdk-generator 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @archastro/sdk-generator 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @archastro/sdk-generator 可以商用吗？ @archastro/sdk-generator 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @archastro/sdk-generator 的下载量有多少？ 根据 npm 官方下载统计，@archastro/sdk-generator 在 2026/10/07 – 2026/11/05 这 30 天内被下载 78,984 次，日均约 2,633 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @archastro/sdk-generator 还在维护吗？ 最新版本 0\.11\.17 发布于 2026/11/04（4 天前）；至今共发布 42 个版本，其中过去 12 个月发布了 42 个；首次发布于 2026/04/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。