80 lines
2.8 KiB
Markdown
80 lines
2.8 KiB
Markdown
# proto — 跨语言 API 契约
|
||
|
||
本目录是系统的**语言中立契约源**。`contract.proto` 定义了内核与插件之间、以及外部系统与本系统交互所需的全部 gRPC 服务与消息。任何语言都可以从这里生成客户端/服务端代码来接入本系统。
|
||
|
||
```
|
||
proto/
|
||
contract/v1/contract.proto 契约源（唯一可信来源）
|
||
```
|
||
|
||
> Go 生成代码位于 `src/go/proto/contract/v1/`（已入库，克隆即可 `go build`）。其它语言的生成代码不入库，由各使用方按需生成。
|
||
|
||
## 契约内容
|
||
|
||
`contract.v1` package 定义：
|
||
|
||
**通用服务（每个插件都实现）**
|
||
- `PluginManifest` — `GetManifest`、`HealthCheck`
|
||
- `InvocationBroker` — `Invoke`（内核托管，插件互调入口）、`ListPlugins`
|
||
|
||
**枚举与基础消息**
|
||
- `PluginTier` — `BASE` / `MID` / `COMPLEX`
|
||
- `Dependency`、`Capability`、`PluginInfo`、`TrafficEntry`、`UsageInfo`
|
||
|
||
**业务服务（由插件实现）**
|
||
- `EchoService`、`TransformService`、`StreamingDemo` — 样例（验证三层与流式）
|
||
- `RecorderService` — 留存与查询（Save/List/ReadBlob/Stats）
|
||
- `UsageService` — 用量解析（ParseBody/ParseStream）
|
||
- `ProxyService` — 外部流量处理入口（Handle）
|
||
- `DashboardService` — 只读管理界面渲染（Render）
|
||
|
||
## 跨语言生成示例
|
||
|
||
先确保安装了 protoc 及对应语言插件，然后从仓库根目录执行（`--proto_path` 指向本目录）。
|
||
|
||
**Python**
|
||
```bash
|
||
python -m grpc_tools.protoc \
|
||
--proto_path=proto \
|
||
--python_out=out/python --grpc_python_out=out/python \
|
||
contract/v1/contract.proto
|
||
```
|
||
|
||
**TypeScript / JavaScript（ts-proto）**
|
||
```bash
|
||
protoc \
|
||
--proto_path=proto \
|
||
--plugin=protoc-gen-ts_proto=./node_modules/.bin/protoc-gen-ts_proto \
|
||
--ts_proto_out=out/ts \
|
||
contract/v1/contract.proto
|
||
```
|
||
|
||
**Java**
|
||
```bash
|
||
protoc \
|
||
--proto_path=proto \
|
||
--java_out=out/java --grpc-java_out=out/java \
|
||
contract/v1/contract.proto
|
||
```
|
||
|
||
**Go**（已配置在 `scripts/genproto.ps1`，无需手动）
|
||
```powershell
|
||
.\scripts\genproto.ps1 # 从 proto/ 生成到 src/go/proto/
|
||
```
|
||
|
||
## 互调约定
|
||
|
||
插件间调用全部经内核 `InvocationBroker.Invoke`：
|
||
- `target_plugin` — 目标插件名（如 `"echo-base"`）
|
||
- `method` — gRPC 方法全路径（如 `"/contract.v1.EchoService/Echo"`）
|
||
- `payload` — 目标请求消息的 proto-wire 字节（用本契约生成的类型序列化）
|
||
|
||
返回的 `result` 是目标响应消息的 proto-wire 字节，用同一契约反序列化即可。内核不感知具体类型，只透传字节——这正是契约必须语言中立、独立存在的原因。
|
||
|
||
## 修改契约
|
||
|
||
改 `contract.proto` 后：
|
||
1. 重新生成 Go 代码：`.\scripts\genproto.ps1`
|
||
2. 提交更新后的 `proto/contract/v1/contract.proto` 与 `src/go/proto/contract/v1/*.pb.go`
|
||
3. 通知各语言使用方按上面的命令重新生成
|