# @airtasker/spot 中文文档 规范地址：https://npmcn.com/package/%40airtasker/spot/ 版本：2\.0\.0 npm 元数据更新时间：2026-01-28T00:57:24.640Z 中文译文更新时间：2026-11-06T03:15:23.300Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40airtasker/spot 原文对照：https://npmcn.com/package/%40airtasker/spot/?lang=original 项目主页：https://github.com/airtasker/spot 源码仓库：https://github.com/airtasker/spot ## 关键信息（来自 npm 元数据） - 包体积（解压后）：1.7 MB，208 个文件 - 模块格式：CommonJS - TypeScript 类型：包内自带 - Node.js 要求：\>=18\.12\.0 - 运行依赖：16 个 - 首次发布：2018-11-27T03:53:19.072Z - 最新版本发布：2026-01-28T00:57:24.451Z - 近 30 天下载量：5841（2026-10-05 至 2026-11-03，npm 官方下载统计） - 已发布版本数：50（近 12 个月 1 个） ## 中文简介 **点** (单位:千美元)_"真理的单一点"_)是一种简洁,开发者友好的方式来描述你的API合同. ## 安装 ```sh npm install @airtasker/spot ``` 也可以使用：`pnpm add @airtasker/spot`、`yarn add @airtasker/spot`、`bun add @airtasker/spot` ## README # 点 **点** (单位:千美元)_"真理的单一点"_)是一种简洁,开发者友好的方式来描述你的API合同. 使用 TypeScript 语法,它允许您描述您的 API 并生成您需要的其他 API 合同格式( OpenAPI, Swagger, JSON Schema) . 您不需要使用代码库中的 TypeScript 来获益于使用 Spot . API 定义文件示例 `api.ts` 定义单个 `POST` 创建用户的结束点 : ```typescript import { api, endpoint, request, response, body } from "@airtasker/spot"; @api({ name: "My API" }) class Api {} @endpoint({ method: "POST", path: "/users" }) class CreateUser { @request request(@body body: CreateUserRequest) {} @response({ status: 201 }) response(@body body: CreateUserResponse) {} } interface CreateUserRequest { firstName: string; lastName: string; } interface CreateUserResponse { firstName: string; lastName: string; role: string; } ``` ## 开始 从写Spot合同开始 [点点指南](https://github.com/airtasker/spot/wiki/Spot-Guide) 关于所有可用的语法,参见 [斑点语法](https://github.com/airtasker/spot/wiki/Spot-Syntax) ### 所需资源 - 节点.js >= 18.12.0 - pnpm( 建议) 或 npm ### 安装 与 [小时](https://pnpm.io/) 安装并初始化 `@airtasker/spot` 对您的项目: ```sh pnpm add @airtasker/spot ``` 只需运行即可将上面的定义传递给生成器 : ```sh npx @airtasker/spot generate --contract api.ts ``` # 为什么我们造出斑点 乍一看,你可能会想知道 为什么我们打扰建筑点。 为什么不使用OpenAPI(形式上称为Swagger)来描述您的API? 在核心,我们建造了Spot,因为我们想要更好的开发者经验. ## 书面合同 OpenAPI文档作为YAML文件存储,遵循非常具体的计划. 您不会知道您使用错误的字段名称, 或忘记将类型定义包装到一个计划对象中, 除非您运行一个好的 OpenAPI linter 。 大多数不熟悉 OpenAPI 规格的开发者最终使用Swagger 编辑器或 Stoplight 等视觉编辑器. 由于 Spot 调用 TypeScript 语法,你只需要写出有效的 TypeScript 代码. 当您的代码无效时, 您的编辑会立即告诉你 。 它会告诉你缺少什么,你甚至可以免费自动完成。 我们本来可以选择任何其他类型的语言——TypeScript恰好是我们最简洁和无所不在的语言之一. ## 审查合同 我们认为API合同应该被检查到Git,或者任何你使用的代码版本系统. 此外,应系统地审查API合同。 后端工程师很难错误地假设客户工程师对终点的期望. 由于其复杂的嵌入式结构以及OpenAPI规格的丰富性,OpenAPI文档在拉出请求中可能难以审查. 他们擅长机器. Spot旨在尽可能能被人类读取. 与我们先前的OpenAPI文件相比. ## 不同格式的互操作性 根据您想要达到的目标(测试,文档,客户端代码生成...),您会找到只和OpenAPI 2(Swagger)合作的工具,以及仅支持OpenAPI 3的更新的工具. 您也可以为不同的 API 生态系统找到工具, 如 JSON Schema 或 API 蓝图 . 我们建Spot就是考虑到这一点。 Spot不需将各种API格式转换器相拼,而是可以生成出每个主要的API文档格式. 这就是为什么我们称之为"真理的单一点". [![oclif](https://img.shields.io/badge/cli-oclif-brightgreen.svg)](https://oclif.io/) [![Version](https://img.shields.io/npm/v/@airtasker/spot.svg)](https://npmjs.org/package/@airtasker/spot) [![CircleCI](https://circleci.com/gh/airtasker/spot/tree/master.svg?style=shield)](https://circleci.com/gh/airtasker/spot/tree/master) [![Downloads/week](https://img.shields.io/npm/dw/@airtasker/spot.svg)](https://npmjs.org/package/@airtasker/spot) [![License](https://img.shields.io/npm/l/@airtasker/spot.svg)](https://github.com/airtasker/spot/blob/master/package.json) - [点](https://npmcn.com/package/%40airtasker/spot/#readme-spot) - [为什么我们造出斑点](https://npmcn.com/package/%40airtasker/spot/#readme-why-we-built-spot) - [使用量](https://npmcn.com/package/%40airtasker/spot/#readme-usage) - [图标](https://npmcn.com/package/%40airtasker/spot/#readme-commands) # 使用量 要在当前目录中启动并设置 API 声明, 运行 : ``` npx @airtasker/spot init ``` 然后,您可以用 : ``` npx @airtasker/spot generate --contract api.ts ``` ## 在记忆使用中 ```ts import { Spot } from "@airtasker/spot"; const contract = Spot.parseContract("./api.ts") const openApi = Spot.OpenApi3.generateOpenAPI3(contract); console.log(openApi); /* { openapi: '3.0.2', info: { title: 'my-api', description: undefined, version: '0.0.0' }, paths: { '/users': { post: [Object] } }, components: { schemas: { CreateUserRequest: [Object], CreateUserResponse: [Object] }, securitySchemes: undefined }, security: undefined } */ ``` # 图标 - [`spot checksum SPOT_CONTRACT`](https://npmcn.com/package/%40airtasker/spot/#readme-spot-checksum-spot_contract) - [`spot docs SPOT_CONTRACT`](https://npmcn.com/package/%40airtasker/spot/#readme-spot-docs-spot_contract) - [`spot generate`](https://npmcn.com/package/%40airtasker/spot/#readme-spot-generate) - [`spot help [COMMAND]`](https://npmcn.com/package/%40airtasker/spot/#readme-spot-help-command) - [`spot init`](https://npmcn.com/package/%40airtasker/spot/#readme-spot-init) - [`spot lint SPOT_CONTRACT`](https://npmcn.com/package/%40airtasker/spot/#readme-spot-lint-spot_contract) - [`spot mock SPOT_CONTRACT`](https://npmcn.com/package/%40airtasker/spot/#readme-spot-mock-spot_contract) - [`spot validate SPOT_CONTRACT`](https://npmcn.com/package/%40airtasker/spot/#readme-spot-validate-spot_contract) - [`spot validation-server SPOT_CONTRACT`](https://npmcn.com/package/%40airtasker/spot/#readme-spot-validation-server-spot_contract) ## `spot checksum SPOT_CONTRACT` 为 Spot 合同生成支票和 ``` USAGE $ spot checksum SPOT_CONTRACT ARGUMENTS SPOT_CONTRACT path to Spot contract OPTIONS -h, --help show CLI help EXAMPLE $ spot checksum api.ts ``` _参见代码 : [构建/cli/src/命令/校验和.js](https://github.com/airtasker/spot/blob/v2.0.0/build/cli/src/commands/checksum.js)_ ## `spot docs SPOT_CONTRACT` 预览 Spot 合同作为 OpenAPI3 文档 。 文件服务器将在http://localhost:8080上启动. ``` USAGE $ spot docs SPOT_CONTRACT ARGUMENTS SPOT_CONTRACT path to Spot contract OPTIONS -h, --help show CLI help -p, --port=port [default: 8080] Documentation server port EXAMPLE $ spot docs api.ts ``` _参见代码 : [构建/cli/src/命令/docs.js](https://github.com/airtasker/spot/blob/v2.0.0/build/cli/src/commands/docs.js)_ ## `spot generate` 运行 API 上的生成器 。 曾出产客户端库,服务器锅炉板和OpenAPI等知名API合同格式. ``` USAGE $ spot generate OPTIONS -c, --contract=contract (required) Path to a TypeScript Contract definition -g, --generator=generator Generator to run -h, --help show CLI help -l, --language=language Language to generate -o, --out=out Directory in which to output generated files EXAMPLE $ spot generate --contract api.ts --language yaml --generator openapi3 --out output/ ``` _参见代码 : [构建/ cli/ src/ commands/ generate.js](https://github.com/airtasker/spot/blob/v2.0.0/build/cli/src/commands/generate.js)_ ## `spot help [COMMAND]` 显示点名帮助 ``` USAGE $ spot help [COMMAND] ARGUMENTS COMMAND command to show help for OPTIONS --all see all commands in CLI ``` _参见代码 : [@oclif/plugin-帮助](https://github.com/oclif/plugin-help/blob/v3.3.1/src/commands/help.ts)_ ## `spot init` 生成锅炉板用于API. ``` USAGE $ spot init OPTIONS -h, --help show CLI help EXAMPLE $ spot init Generated the following files: - api.ts - tsconfig.json - package.json ``` _参见代码 : [构建/cli/src/命令/init.js](https://github.com/airtasker/spot/blob/v2.0.0/build/cli/src/commands/init.js)_ ## `spot lint SPOT_CONTRACT` 定点合同 ``` USAGE $ spot lint SPOT_CONTRACT ARGUMENTS SPOT_CONTRACT path to Spot contract OPTIONS -h, --help show CLI help --has-discriminator=(error|warn|off) Setting for has-discriminator --has-request-payload=(error|warn|off) Setting for has-request-payload --has-response=(error|warn|off) Setting for has-response --has-response-payload=(error|warn|off) Setting for has-response-payload --no-inline-objects-within-unions=(error|warn|off) Setting for no-inline-objects-within-unions --no-nullable-arrays=(error|warn|off) Setting for no-nullable-arrays --no-nullable-fields-within-request-bodies=(error|warn|off) Setting for no-nullable-fields-within-request-bodies --no-omittable-fields-within-response-bodies=(error|warn|off) Setting for no-omittable-fields-within-response-bodies --no-trailing-forward-slash=(error|warn|off) Setting for no-trailing-forward-slash EXAMPLES $ spot lint api.ts $ spot lint --has-descriminator=error $ spot lint --no-nullable-arrays=off ``` _参见代码 : [构建/cli/src/命令/lint.js](https://github.com/airtasker/spot/blob/v2.0.0/build/cli/src/commands/lint.js)_ ## `spot mock SPOT_CONTRACT` 根据 Spot 合同运行一个模拟服务器 ``` USAGE $ spot mock SPOT_CONTRACT ARGUMENTS SPOT_CONTRACT path to Spot contract OPTIONS -h, --help show CLI help -p, --port=port (required) [default: 3010] Port on which to run the mock server --pathPrefix=pathPrefix Prefix to prepend to each endpoint path --proxyBaseUrl=proxyBaseUrl If set, the server will act as a proxy and fetch data from the given remote server instead of mocking it --proxyFallbackBaseUrl=proxyFallbackBaseUrl Like proxyBaseUrl, except used when the requested API does not match defined SPOT contract. If unset, 404 will always be returned. --proxyMockBaseUrl=proxyMockBaseUrl Like proxyBaseUrl, except used to proxy draft endpoints instead of returning mocked responses. EXAMPLE $ spot mock api.ts ``` _参见代码 : [构建/cli/src/命令/mock.js](https://github.com/airtasker/spot/blob/v2.0.0/build/cli/src/commands/mock.js)_ ## `spot validate SPOT_CONTRACT` 验证Spot合同 ``` USAGE $ spot validate SPOT_CONTRACT ARGUMENTS SPOT_CONTRACT path to Spot contract OPTIONS -h, --help show CLI help EXAMPLE $ spot validate api.ts ``` _参见代码 : [构建/ cli/ src/ 命令/ 验证.js](https://github.com/airtasker/spot/blob/v2.0.0/build/cli/src/commands/validate.js)_ ## `spot validation-server SPOT_CONTRACT` 启动现场合同验证服务器 ``` USAGE $ spot validation-server SPOT_CONTRACT ARGUMENTS SPOT_CONTRACT path to Spot contract OPTIONS -h, --help show CLI help -p, --port=port [default: 5907] The port where application will be available EXAMPLE $ spot validation-server api.ts ``` _参见代码 : [构建/cli/src/命令/验证-服务器.js](https://github.com/airtasker/spot/blob/v2.0.0/build/cli/src/commands/validation-server.js)_ ## 常见问题 ### @airtasker/spot 是什么？ 点 \(单位:千美元\)"真理的单一点"\)是一种简洁,开发者友好的方式来描述你的API合同\. ### 如何安装 @airtasker/spot？ 在项目目录运行 npm install @airtasker/spot，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 spot，可以用 npx spot 直接运行。 ### @airtasker/spot 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @airtasker/spot 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @airtasker/spot 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=18\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @airtasker/spot 可以商用吗？ @airtasker/spot 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @airtasker/spot 的下载量有多少？ 根据 npm 官方下载统计，@airtasker/spot 在 2026/10/05 – 2026/11/03 这 30 天内被下载 5,841 次，日均约 195 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @airtasker/spot 还在维护吗？ 最新版本 2\.0\.0 发布于 2026/01/28（9 个月前）；至今共发布 50 个版本，其中过去 12 个月发布了 1 个；首次发布于 2018/11/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。