# @aptre/common 中文文档

规范地址：https://npmcn.com/package/%40aptre/common/

版本：0\.38\.2
npm 元数据更新时间：2026-11-07T16:10:53.718Z
中文译文更新时间：2026-11-06T13:03:52.726Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aptre/common
原文对照：https://npmcn.com/package/%40aptre/common/?lang=original
项目主页：https://github.com/aperturerobotics/common#readme
源码仓库：https://github.com/aperturerobotics/common

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：371 kB，71 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2024-04-24T05:57:48.845Z
- 最新版本发布：2026-11-07T16:10:53.344Z
- 近 30 天下载量：23801（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：125（近 12 个月 59 个）

## 中文简介

常见的项目配置文件和依赖性.

## 安装

```sh
npm install @aptre/common
```

也可以使用：`pnpm add @aptre/common`、`yarn add @aptre/common`、`bun add @aptre/common`

## README

# 常见

[![GoDoc Widget](https://godoc.org/github.com/aperturerobotics/common?status.svg)](https://godoc.org/github.com/aperturerobotics/common) [![npm Widget](https://img.shields.io/npm/v/@aptre/common.svg)](https://www.npmjs.com/package/@aptre/common)

> Go, TypeScript, C++, Rust 与 WASM 统一原生出代码生成.

## 这是什么?

此寄存器提供 `aptre` CLI — 一个生成 protobuf 代码用于 **四种语言** 不要求您安装原型、原型插件或语言专用工具链。 使用嵌入式 WebAssembly 模块运行 [维罗](https://github.com/tetratelabs/wazero)。 。 。 .

### 关键特性

-   **零原生属地** ——原型和插件以 WASM 运行,不需要安装
-   **多语种产出** — 从单个命令生成 Go, TypeScript, C++, 和 Rust
-   **智能缓存** – 只有在源文件实际更改时才重新生成
-   **GO 式导入** 在您使用熟悉的导入路径 `.proto` 文件

## 支持的语言

| 语言 | 信件类型 | RPC服务 | 插件 |
| --- | --- | --- | --- |
| 走开 | `*.pb.go` | `*_srpc.pb.go` | [(原始内容存档于2019-09-31) (英语). protobuf-go-lite](https://github.com/aperturerobotics/protobuf-go-lite) |
| 类型脚本 | `*.pb.ts` | `*_srpc.pb.ts` | [(原始内容存档于2018-10-21) (英语). protobuf-es-lite](https://github.com/aperturerobotics/protobuf-es-lite) |
| C++ 组合 | `*.pb.cc/h` | `*_srpc.pb.hpp/cpp` | 内建原型+ [星点](https://github.com/aperturerobotics/starpc) |
| 锈 | `*.pb.rs` | `*_srpc.pb.rs` | [敬礼](https://github.com/tokio-rs/prost) (WASI) + (中文(简体) ) [星点](https://github.com/aperturerobotics/starpc) |

## 稳定型号

信件可以使用 `(typeid.id)` 选项 :

```protobuf
import "github.com/aperturerobotics/common/typeid/typeid.proto";

message CreateFile {
  option (typeid.id) = "fs/create-file";

  string path = 1;
}
```

对于每个原始文件 带有这种消息, `aptre generate` 写入 `*_typeid.pb.go` 持有 `CreateFileTypeID` 常数, a `TypeID()` 方法, 和文档的 `[]typeid.Type` 清单(`OpsTypes` 页:1 `ops.proto`每个对齐 带有构建器的标识符。 发电机在电流内运行 所以不需要 插件二进制 。 生成器拒绝相同文件中的两个信件 标识符; 从多个列表检查中构建一个登记册的应用程序 其余部分.

C++ 构建导入选项并编译 `typeid/typeid.pb.cc`; 其他 语言忽略它.

## 通过 WASI 的 Rust 支持

Rust 代码生成使用嵌入式 [刚才](https://wasi.dev/) 建造 `protoc-gen-prost`,含义 **你不需要货物 生锈器 或安装任何 Rust工具链** 生成 `.pb.rs` 文档。 Prost插件完全运行在Wazero Web Assembly 运行时间与protoc本身.

这是由 [去 - protoc - gen - pros](https://github.com/aperturerobotics/go-protoc-gen-prost),它嵌入了 ~600KB WASM 二进制,可以执行完整的prost protobuf 代码生成器.

### 示例输出

鉴于一个简单的原始文件:

```protobuf
syntax = "proto3";
package echo;

message EchoMsg {
  string body = 1;
}
```

生成的 `echo.pb.rs`数字 :

```rust
// @generated
// This file is @generated by prost-build.
#[derive(Clone, PartialEq, Eq, Hash, ::prost::Message)]
pub struct EchoMsg {
    #[prost(string, tag="1")]
    pub body: ::prost::alloc::string::String,
}
```

见 [星点](https://github.com/aperturerobotics/starpc) 一个完整的例子.

## 安装

```bash
# Run directly (no install needed)
go run github.com/aperturerobotics/common/cmd/aptre@latest generate

# Or install globally
go install github.com/aperturerobotics/common/cmd/aptre@latest
```

## 快速启动

1.  **设置您的项目** 带有 Go 和可选类型脚本 :

```bash
# Initialize Go module
go mod init github.com/yourorg/yourproject
```

2.  **创建原始文件** 使用 GO 式导入 :

```protobuf
syntax = "proto3";
package example;

// Import .proto files using Go-style import paths
import "github.com/aperturerobotics/controllerbus/controller/controller.proto";

message GetBusInfoResponse {
  repeated controller.Info running_controllers = 1;
}
```

3.  **生成代码**数字 :

```bash
# Stage files for git (required for discovery)
git add -A

# Generate all languages
go run github.com/aperturerobotics/common/cmd/aptre@latest generate

# Generate only Go output
go run github.com/aperturerobotics/common/cmd/aptre@latest generate --language go

# Or with verbose output
go run github.com/aperturerobotics/common/cmd/aptre@latest generate --verbose
```

## CLI 命令

| 命令 | 说明 |
| --- | --- |
| `generate` | 生成 protobuf 代码( Go, TypeScript, C++, Rust) |
| `generate --force` | 重新生成所有文件, 忽略缓存 |
| `clean` | 删除已生成的文件和缓存 |
| `deps` | 确保安装所有依赖 |
| `lint` | 运行高朗奇林特 |
| `fix` | 用 -- fix 运行 golangci-lint 运行 |
| `test` | 运行测试 |
| `test --browser` | 用 WebAssembly 在浏览器中运行测试 |
| `format` | 格式 与 gofumt 编码 |
| `outdated` | 显示过时的依赖性 |

## TLA+ 东加 光谱

`aptre-tla` 检查 TLA+ 规格 [la-ts](https://github.com/aidenybai/tla-ts), (中文(简体) ), 在节点或邦没有Java。 光谱 `Foo.tla` 每个模型配置检查一次 旁边是: `Foo.cfg` 和每个 `Foo-<variant>.cfg`A级 `.tla` 没有配置是 帮助模块 。 模块名称从 spec 目录解析,然后从 共享模块 `tla/`数字 :

-   `Surface.tla`:规则每个屏幕都为每一个能达到它的人保留. `EveryShownActionWorks` 当一个人看到的每一个行动都成功时 他们; `NobodyIsStuck` 当每个人都有事情要做时,就按住.

```bash
# Check every spec under the current directory
bunx aptre-tla
# Check one spec or one directory
bunx aptre-tla pkg/foo/Foo.tla
```

失败会打印出破损的规则和最短的路径, 每条状态 ,命令输出为 1。 项目添加到其检查脚本中作为 `"check:tla": "aptre-tla"`编辑 `@aptre/common/tla` 出口报价 `findModels` 财务报告和审定财务报表 `checkModel` 对于工具,如承诺钩.

## 如何运作

这个 `aptre` 使用嵌入式WebAssembly 生成代码:

1.  **发现** - 发现 `.proto` 匹配您目标的文件( 默认 ): `./*.proto`(中文(简体) )
2.  **缓存** - 检查 `.protoc-manifest.json` 跳过未修改的文件
3.  **原生生物(WASM)** —运行 [去 - protoc -wasi (英语)](https://github.com/aperturerobotics/go-protoc-wasi) 来解析原型并引用插件
4.  **插件** —— Go/TS 本地插件, Rust (prost) 的 WASM 插件
5.  **后处理** - 修复进口和产出格式

### 建筑

```
┌─────────────────────────────────────────────────────────────┐
│                         aptre CLI                           │
├─────────────────────────────────────────────────────────────┤
│                     wazero runtime                          │
├─────────────┬─────────────────────────┬─────────────────────┤
│ protoc.wasm │  protoc-gen-prost.wasm  │   Native Plugins    │
│  (parsing)  │     (Rust output)       │  (Go, TS, C++)      │
└─────────────┴─────────────────────────┴─────────────────────┘
```

## C++ 组合 支助

C++ protobuf 文件 (`.pb.cc` 财务报告和审定财务报表 `.pb.h`与其他产出一起产生。 添加 `vendor/` 转到包含路径 :

```cmake
# CMakeLists.txt
include_directories(${PROJECT_SOURCE_DIR}/vendor)
```

```cpp
#include "github.com/yourorg/yourproject/example/example.pb.h"
```

对于StarPC C++服务 `*_srpc.pb.hpp` 文档提供客户端/服务器根.

## 配置

生成器使用合理的默认但可以定制:

-   **目标**: Proto 文件模式(默认值 : `./*.proto`(中文(简体) )
-   **不包括**: 跳过的模式(例如, `vendor/**`(中文(简体) )
-   **工具目录**: 插件二进制位置( 默认 ): `.tools`(中文(简体) )
-   **缓存**备忘文件( 默认 ): `.protoc-manifest.json`(中文(简体) )

### `package.json` 配置

当雷波有 `package.json`, (中文(简体) ), `aptre generate` 还读取了可选 顶级 `aptre` 从中配置对象 .

示例

```json
{
  "name": "spacewave",
  "private": true,
  "aptre": {
    "languages": ["go", "ts", "cpp", "rust"],
    "tsImportBoundaries": ["auth", "bldr", "db", "forge", "identity", "net"]
  }
}
```

### `aptre.languages`

`languages` 选择要生成的输出语言。 支持的值为 `go`, (中文(简体) ), `ts`, (中文(简体) ), `cpp`, (中文(简体) ), `rust`, (中文(简体) ), `csharp`,以及 `python`. C#和Python是选入. 奥米 `languages` 以保存已存在的默认值:生成 Go、 C++ 和 Rust 当项目有 `go.mod`,加 TypeScript 当它有一个 `package.json`。 。 。 .

CLI 旗帜优先 `package.json`数字 :

```bash
aptre generate --language go
```

### `aptre.rust`

设置 `aptre.rust` 制造 `aptre generate` 将整个图集汇编为 单跑和写一个 Rust 文件 每个计划, 旁边的计划, 即使一个 protobuf包跨越了多个目录. 其它选择的语言 使用每个指令生成器.

```json
{
  "aptre": {
    "module": "example.com/app",
    "languages": ["rust"],
    "rust": {
      "prostOptions": ["enable_type_names", "btree_map=."],
      "exclude": [],
      "descriptorSet": "wire/descriptors.bin",
      "moduleFile": "wire/messages.rs",
      "inventory": ".protoc-rust-files.txt"
    }
  }
}
```

-   `module` 是工程计划前缀的导入路径。 默认 页:1 `go.mod` 模块,所以一个没有 `go.mod` 必须设定它。 示马斯 下级 `vendor/` 保存目录中的导入路径 .
-   `prostOptions` 将按顺序传递到正体插件。 用于类型 名称、确定性地图、框字段和 `extern_path` 测绘.
-   `exclude` 列出不编译的图案.
-   `descriptorSet` 收到全图的序式描述符, 包括进口和来源信息,供运行时间反省.
-   `moduleFile` 接收 `include!` 每一个生成文件的嵌入声明 在其原生包下,将每个段命名为Prost(snake case, `r#` 关键词).
-   `inventory` 列出每个生成的路径。 下一次运行将删除文件 清单名称,但计划不再产生.

选择方案 `--targets`。产出首先在内存中构建并写入 只有当它们的字节改变. `aptre generate --check --language rust` 比较 不写的所有输出, 打印每个 `outdated:` 路径和退出非零. 检查从不准备依赖性 : `rpc` 包含 `starpc` 财务报告和审定财务报表 `protoc-gen-starpc-rust` 没有构建, 它失败并命名了缺失的插件 ; 运行 `aptre deps` 先说.

`tests/rust-graph/check.bash` 生成带有各种类型路径的工程, 检查一下,并运行 Rust 测试 准确的输出.

### `aptre.tsTypedDecode`

`tsTypedDecode` 制造 `protoc-gen-es-lite` 生成每次输入的解码器 信件, a `switch` 在字段号码 直接读到消息, 替换共享的行走器:

```json
{
  "aptre": {
    "tsTypedDecode": true
  }
}
```

打开用于运行在 JavaScript 解释器中的代码, 如 QuickJS 或 即一个超时编译器,其中输入的解码器更快。 这个 使生成的文件更大,在JIT下,行走者一样快,所以它 默认关闭.

### `aptre.tsTypedEncode`

`tsTypedEncode` 编码时也这样做 : `protoc-gen-es-lite` 生成一个 按数字顺序写出每个字段的信件的编码器 与共享的字节行走器相同 。 这需要 `@aptre/protobuf-es-lite` 1.2.4 或 后经. 同样的理由也适用:对口译和口译人员适用 超时编译器, 把它放在JIT下.

### `aptre.tsImportBoundaries`

`tsImportBoundaries` 配置生成的 TypeScript protobuf 导入方式 在单簧管内部重写.

默认情况下,同一模块产生的进口仍然相对存在。 这通常是 你想在单打包的回放.

对于生成多位顶级成员的原生取出TypeScript的单体, 当一个构建系统将来源映射到另一个树上时, 相对导入会中断 或每个成员需要稳定的再根导入路径。 在这种情况下,定义 模块相对边界前缀 `aptre.tsImportBoundaries`。 。 。 .

当生成时 `*.pb.ts` 文件导入另一个生成的 protobuf 文件 :

-   如果导入仍停留在同一配置的边界内,则仍然相对.
-   如果导入从一个配置的边界跨越到另一个边界, `aptre` 重写为 `@go/...` 导入.
-   在当前模块外解析的导入仍然重写到 `@go/...` 从 `vendor/` 和以前一样.

鉴于:

```json
{
  "aptre": {
    "tsImportBoundaries": ["bldr", "db"]
  }
}
```

如:

```ts
import { VolumeInfo } from '../../db/volume/volume.pb.js'
```

内 `bldr/plugin/plugin.pb.ts` 改为:

```ts
import { VolumeInfo } from '@go/github.com/yourorg/yourrepo/db/volume/volume.pb.js'
```

边界条目与 Go 模块根的路径相匹配, 所以 它们应该命名 repo 目录, 如 `bldr`, (中文(简体) ), `db`,或 `net`未满 模块路径.

## 相关项目

-   [星点](https://github.com/aperturerobotics/starpc) – 为 Go, TypeScript 和 Rust 流出 RPC
-   [(原始内容存档于2019-09-31) (英语). protobuf-go-lite](https://github.com/aperturerobotics/protobuf-go-lite) 轻型 不反射去原地取出
-   [(原始内容存档于2018-10-21) (英语). protobuf-es-lite](https://github.com/aperturerobotics/protobuf-es-lite) ——轻量级 TypeScript protobuf
-   [去 - protoc -wasi (英语)](https://github.com/aperturerobotics/go-protoc-wasi) - 嵌入原型为WASM
-   [去 - protoc - gen - pros](https://github.com/aperturerobotics/go-protoc-gen-prost) ——作为 WASM 的 prost 插件
-   [模板](https://github.com/aperturerobotics/template) — 使用此软件包的项目模板
-   [原生项目](https://github.com/aperturerobotics/protobuf-project) - 更广泛的实例

## 支助

请打开一个 [GitHub 问题](https://github.com/aperturerobotics/common/issues/new) 有问题或问题.

...或联系 [矩阵聊天](https://matrix.to/#/#aperturerobotics:matrix.org) 或者说 [解析器](https://discord.gg/KJutMESRsT)。 。 。 .

## 许可证

麻省理工学院

## 常见问题

### @aptre/common 是什么？

常见的项目配置文件和依赖性\.

### 如何安装 @aptre/common？

在项目目录运行 npm install @aptre/common，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 aptre-tla，可以用 npx aptre-tla 直接运行。

### @aptre/common 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aptre/common 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @aptre/common 可以商用吗？

@aptre/common 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @aptre/common 的下载量有多少？

根据 npm 官方下载统计，@aptre/common 在 2026/10/07 – 2026/11/05 这 30 天内被下载 23,801 次，日均约 793 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aptre/common 还在维护吗？

最新版本 0\.38\.2 发布于 2026/11/08（今天）；至今共发布 125 个版本，其中过去 12 个月发布了 59 个；首次发布于 2024/04/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。