# protoc-gen-typescript-http

**Repository Path**: LiuChamp/protoc-gen-typescript-http

## Basic Information

- **Project Name**: protoc-gen-typescript-http
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-22
- **Last Updated**: 2026-03-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# protoc-gen-typescript-http

这是一个 `protoc` 插件，可从带有 [`google.api.http`](https://github.com/googleapis/googleapis/blob/master/google/api/http.proto) 注解规则的 Protocol Buffers 定义中生成 TypeScript 类型和服务客户端。

生成的类型会直接映射到 [canonical JSON encoding](https://developers.google.com/protocol-buffers/docs/proto3#json) 格式。

**实验性**：该库仍在积极开发中，不同版本之间的配置文件、API 和生成代码可能会发生破坏性变更。

## 功能特性

- **TypeScript 定义生成**：自动为 Protobuf 消息和枚举生成高精度的 TypeScript `type` 与 `interface` 绑定。
- **HTTP/REST 客户端**：基于 `google.api.http` 注解，为 `service` 定义生成映射到 REST 端点的客户端桩代码。
- **与 HTTP 库解耦**：生成的客户端不绑定具体 HTTP 库。它会生成接收简单处理函数的工厂方法（例如 `fetch` 或 `axios`），可在 Node.js、浏览器、React Native 等环境使用。
- **支持 Buf**：原生支持基于 [Buf](https://buf.build) 的代码生成流水线。
- **现代化构建流程**：通过 [Mage](https://magefile.org/) 管理自动化构建、Lint 和测试。

## 安装

### 从源码安装

请确保已安装 [Go](https://golang.org/) 1.26 或更高版本，然后执行：

```bash
go install go.einride.tech/protoc-gen-typescript-http@latest
```

### 下载预编译二进制

你也可以直接从 [Releases](./releases) 页面下载预编译二进制文件。

## 使用方式

如需查看带有正确注解的 protobuf 定义以及生成的 TypeScript 代码完整示例，请参考 [`examples`](./examples) 目录。

### 配合 Buf 使用（推荐）

在 `buf.gen.yaml` 中添加插件：

```yaml
version: v1
plugins:
  - name: typescript-http
    out: gen/typescript
```

然后执行生成命令：

```bash
buf generate
```

### 使用 `protoc`

```bash
protoc \
  --typescript-http_out [OUTPUT DIR] \
  [.proto files ...]
```

## 使用生成的客户端

生成的客户端会暴露工厂方法，可接入任意返回 JSON `Promise` 的 HTTP 传输实现。下面是使用原生 `fetch` API 的示例：

```typescript
// 导入生成的工厂方法
import { createFreightServiceClient } from "./gen/typescript/einride/example/freight/v1";

const rootUrl = "https://api.example.com";

// 处理函数期望的请求结构
type Request = {
  path: string;
  method: string;
  body: string | null;
};

// 1. 实现自定义请求处理函数
function fetchRequestHandler({ path, method, body }: Request) {
  return fetch(rootUrl + path, {
    method,
    body,
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer YOUR_TOKEN_HERE", // 按需添加鉴权逻辑
    },
  }).then((response) => {
    if (!response.ok) {
      throw new Error(`HTTP Error: ${response.status}`);
    }
    return response.json();
  });
}

// 2. 用处理函数实例化客户端
export const freightClient = createFreightServiceClient(fetchRequestHandler);

// 3. 发起强类型 API 调用
async function run() {
  const shipper = await freightClient.GetShipper({
    name: "shippers/1",
  });
  console.log("Shipper:", shipper);
}
```

## 开发与贡献

本项目的构建流程由 [Mage](https://magefile.org/) 管理。

### 前置条件

```bash
go install github.com/magefile/mage@latest
```

### 常用命令

- **构建项目**：`make build`
- **运行测试**：`make test`
- **代码检查**：`make lint`（执行 Go 和 TypeScript Lint）
- **格式化代码**：`make format`
- **生成示例代码**：`make proto`
- **运行全部检查**：`make all`

如需查看所有可用任务，请执行：

```bash
make help
```