419 lines
15 KiB
Markdown
419 lines
15 KiB
Markdown
# gobridge
|
||
|
||
在 Go 与 Python 之间建立双向通信桥接，将 Go 的 `channel` 与 Python 的 `yield` 原生对接，支持普通调用、单向流、双向流。
|
||
|
||
底层通过 **Unix Domain Socket (UDS)** 通信，Go 侧维护 **Worker 进程池**，Python 侧以多线程方式并发处理请求。
|
||
|
||
## 特性
|
||
|
||
- **零配置序列化**：Go struct/slice ↔ Python dict/list 通过 JSON 自动互转
|
||
- **原生流语义**：Go `chan T` 对应 Python `Iterator[T]`，无需额外 API
|
||
- **进程池**：Go 自动启动并管理多个 Python 子进程，崩溃后自动重启
|
||
- **ctx 取消**：Go `context` 取消时自动中断 Python 计算，无需函数内检查
|
||
- **四种调用模式**：普通、流式输出、流式输入、双向流，同一个 `Invoke` 函数自动推断
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
go get git.fsdpf.net/go/gobridge
|
||
```
|
||
|
||
Python 端直接复制 `python/gobridge/` 目录到项目中，无需安装依赖（仅用标准库）。
|
||
|
||
## 快速开始
|
||
|
||
**Python 端（worker.py）：**
|
||
|
||
```python
|
||
from gobridge import gobridge, run
|
||
from typing import Iterator
|
||
|
||
@gobridge
|
||
def add(a: int, b: int) -> int:
|
||
return a + b
|
||
|
||
run()
|
||
```
|
||
|
||
**Go 端：**
|
||
|
||
```go
|
||
pool, _ := gobridge.NewPool("worker.py")
|
||
defer pool.Close()
|
||
|
||
ctx := context.Background()
|
||
sum, _ := gobridge.Invoke[int](ctx, pool, "add", 3, 4)
|
||
fmt.Println(sum) // 7
|
||
```
|
||
|
||
## 四种调用模式
|
||
|
||
### 1. 普通调用
|
||
|
||
```go
|
||
// Go
|
||
sum, err := gobridge.Invoke[int](ctx, pool, "add", 3, 4)
|
||
|
||
user, err := gobridge.Invoke[User](ctx, pool, "get_user", 42)
|
||
|
||
result, err := gobridge.Invoke[[]User](ctx, pool, "enrich_users", users)
|
||
```
|
||
|
||
```python
|
||
# Python
|
||
@gobridge
|
||
def add(a: int, b: int) -> int:
|
||
return a + b
|
||
|
||
@gobridge
|
||
def get_user(uid: int) -> dict:
|
||
return {"id": uid, "name": f"user_{uid}", "score": uid * 1.5}
|
||
|
||
@gobridge
|
||
def enrich_users(users: list) -> list:
|
||
for u in users:
|
||
u["level"] = "gold" if u["score"] >= 10 else "silver"
|
||
return users
|
||
```
|
||
|
||
### 2. 流式输出（Python yield → Go channel）
|
||
|
||
返回类型为 `chan T` 时自动进入流式输出模式，Python 函数使用 `yield`，Go 侧通过 `range` 消费。
|
||
|
||
```go
|
||
// Go
|
||
ch, err := gobridge.Invoke[chan int](ctx, pool, "range_gen", 1, 6)
|
||
for v := range ch {
|
||
fmt.Println(v) // 1 2 3 4 5
|
||
}
|
||
|
||
userCh, err := gobridge.Invoke[chan User](ctx, pool, "gen_users", 3)
|
||
for u := range userCh {
|
||
fmt.Println(u)
|
||
}
|
||
```
|
||
|
||
```python
|
||
# Python
|
||
@gobridge
|
||
def range_gen(start: int, stop: int) -> Iterator[int]:
|
||
for i in range(start, stop):
|
||
yield i
|
||
|
||
@gobridge
|
||
def gen_users(count: int) -> Iterator[dict]:
|
||
for i in range(1, count + 1):
|
||
yield {"id": i, "name": f"user_{i}", "score": float(i * 3)}
|
||
```
|
||
|
||
### 3. 流式输入（Go channel → Python Iterator）
|
||
|
||
参数中含 `chan T` 且返回非 `chan` 时自动进入流式输入模式。
|
||
|
||
```go
|
||
// Go
|
||
inputCh := make(chan int, 10)
|
||
go func() {
|
||
for i := 1; i <= 5; i++ {
|
||
inputCh <- i
|
||
}
|
||
close(inputCh)
|
||
}()
|
||
total, err := gobridge.Invoke[int](ctx, pool, "sum_stream", inputCh)
|
||
fmt.Println(total) // 15
|
||
```
|
||
|
||
```python
|
||
# Python
|
||
@gobridge
|
||
def sum_stream(numbers: Iterator[int]) -> int:
|
||
return sum(numbers)
|
||
```
|
||
|
||
### 4. 双向流（Go channel 输入 + Go channel 输出）
|
||
|
||
参数含 `chan T` 且返回类型也为 `chan R` 时自动进入双向流模式。
|
||
|
||
```go
|
||
// Go
|
||
inCh := make(chan User, 5)
|
||
go func() {
|
||
for _, u := range users {
|
||
inCh <- u
|
||
}
|
||
close(inCh)
|
||
}()
|
||
outCh, err := gobridge.Invoke[chan User](ctx, pool, "process_users", inCh)
|
||
for u := range outCh {
|
||
fmt.Println(u)
|
||
}
|
||
```
|
||
|
||
```python
|
||
# Python
|
||
@gobridge
|
||
def process_users(users: Iterator[dict]) -> Iterator[dict]:
|
||
for u in users:
|
||
yield {"id": u["id"], "name": u["name"].upper(), "score": u["score"] * 2}
|
||
```
|
||
|
||
## ctx 取消
|
||
|
||
Go 的 `context` 取消会自动中断 Python 侧的执行，无需在 Python 函数中做任何检查：
|
||
|
||
```go
|
||
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
|
||
defer cancel()
|
||
|
||
// 超时或手动 cancel() 后，Python 计算立即中断，返回 context.DeadlineExceeded
|
||
result, err := gobridge.Invoke[int](ctx, pool, "slow_compute", 1000000)
|
||
```
|
||
|
||
```python
|
||
@gobridge
|
||
def slow_compute(n: int) -> int:
|
||
total = 0
|
||
for i in range(n):
|
||
total += i # ctx 取消时此处自动抛出 InterruptedError，无需手动检查
|
||
return total
|
||
```
|
||
|
||
**实现机制：**
|
||
1. Go ctx 取消 → 发送 `cancel` 消息给 Python
|
||
2. Python 单 reader 线程收到 `cancel` → 向执行线程注入 `InterruptedError`（`PyThreadState_SetAsyncExc`）
|
||
3. Python 函数在下一条字节码指令处中断
|
||
4. Go 同时关闭连接，解除阻塞的读写操作
|
||
|
||
> 限制：长时间不释放 GIL 的 C 扩展（如大规模 numpy 矩阵运算）无法被中断，需等其释放 GIL 后才触发。
|
||
|
||
## 进程自动重启
|
||
|
||
Python worker 进程崩溃时自动重启，调用方无感知：
|
||
|
||
```
|
||
Python 进程崩溃
|
||
→ monitor goroutine 检测到退出
|
||
→ 排空失效连接
|
||
→ 指数退避重启（100ms → 200ms → ... → 30s）
|
||
→ 新进程就绪后恢复连接池
|
||
```
|
||
|
||
## 配置
|
||
|
||
`NewPool` 使用函数选项模式，第一个参数为脚本路径：
|
||
|
||
```go
|
||
// 最简调用
|
||
pool, err := gobridge.NewPool("worker.py")
|
||
|
||
// 完整配置
|
||
pool, err := gobridge.NewPool("worker.py",
|
||
gobridge.WithWorkers(4), // Python 进程数量，默认 2
|
||
gobridge.WithMaxConns(8), // 每进程最大连接数，默认 4
|
||
gobridge.WithPythonExe("python3"), // 可执行文件，默认 "python3"
|
||
gobridge.WithWorkDir("/path/to/workdir"), // 工作目录，默认继承当前进程
|
||
gobridge.WithEnv("PYTHONUNBUFFERED=1", "K=V"), // 附加环境变量，与当前进程环境合并
|
||
gobridge.WithSocketDir("/var/run/myapp"), // socket 文件目录，默认 /tmp
|
||
gobridge.WithStdout(os.Stdout), // 子进程 stdout，默认 os.Stdout
|
||
gobridge.WithStderr(os.Stderr), // 子进程 stderr，默认 os.Stderr
|
||
)
|
||
|
||
// 静默模式：丢弃子进程输出
|
||
pool, err := gobridge.NewPool("worker.py",
|
||
gobridge.WithStdout(io.Discard),
|
||
gobridge.WithStderr(io.Discard),
|
||
)
|
||
```
|
||
|
||
| Option | 说明 | 默认值 |
|
||
|--------|------|--------|
|
||
| `WithWorkers(n)` | Python 进程数量 | `2` |
|
||
| `WithMaxConns(n)` | 每进程最大连接数 | `4` |
|
||
| `WithPythonExe(exe)` | 可执行文件 | `"python3"` |
|
||
| `WithScriptArgs(args...)` | 脚本路径之后的附加参数 | 无 |
|
||
| `WithWorkDir(dir)` | 子进程工作目录 | 继承当前进程 |
|
||
| `WithEnv(kv...)` | 附加环境变量 `"K=V"` | 无 |
|
||
| `WithSocketDir(dir)` | UDS socket 文件目录 | `"/tmp"` |
|
||
| `WithStdout(w)` | 子进程标准输出 | `os.Stdout` |
|
||
| `WithStderr(w)` | 子进程标准错误 | `os.Stderr` |
|
||
|
||
## 使用 uv 管理 Python 环境
|
||
|
||
推荐使用 [uv](https://github.com/astral-sh/uv) 管理 Python 版本和虚拟环境。
|
||
|
||
**方式一：`uv run`（推荐，无需手动激活环境）**
|
||
|
||
```go
|
||
// 等价于执行：uv run worker.py
|
||
pool, err := gobridge.NewPool("run",
|
||
gobridge.WithPythonExe("uv"),
|
||
gobridge.WithScriptArgs("worker.py"),
|
||
gobridge.WithWorkDir("./worker"), // uv 项目目录（含 pyproject.toml）
|
||
)
|
||
```
|
||
|
||
**方式二：直接使用虚拟环境的 python**
|
||
|
||
```bash
|
||
cd worker && uv sync
|
||
```
|
||
|
||
```go
|
||
venvPython, _ := exec.LookPath("worker/.venv/bin/python")
|
||
pool, err := gobridge.NewPool("worker/worker.py",
|
||
gobridge.WithPythonExe(venvPython),
|
||
)
|
||
```
|
||
|
||
**方式三：shell 脚本封装（适合 CI/部署）**
|
||
|
||
```bash
|
||
#!/bin/sh
|
||
# run_worker.sh
|
||
cd "$(dirname "$0")"
|
||
exec uv run python worker.py
|
||
```
|
||
|
||
```go
|
||
pool, err := gobridge.NewPool("./run_worker.sh",
|
||
gobridge.WithPythonExe("/bin/sh"),
|
||
)
|
||
```
|
||
|
||
**典型项目结构：**
|
||
|
||
```
|
||
myproject/
|
||
├── main.go
|
||
├── go.mod
|
||
└── worker/
|
||
├── pyproject.toml
|
||
├── uv.lock
|
||
├── .venv/
|
||
└── worker.py
|
||
```
|
||
|
||
`pyproject.toml`：
|
||
|
||
```toml
|
||
[project]
|
||
name = "worker"
|
||
version = "0.1.0"
|
||
requires-python = ">=3.11"
|
||
dependencies = []
|
||
|
||
[tool.uv.sources]
|
||
gobridge = { path = "../../python", editable = true }
|
||
```
|
||
|
||
## 通信协议
|
||
|
||
### 整体架构
|
||
|
||
```
|
||
Go 进程
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ Invoke[R](ctx, pool, method, args...) │
|
||
│ │ │
|
||
│ ┌────▼─────────────────────────────────────────────┐ │
|
||
│ │ Pool │ │
|
||
│ │ workers[0] workers[1] ... workers[N-1] │ │
|
||
│ │ （轮询选择） │ │
|
||
│ └────┬─────────────────────────────────────────────┘ │
|
||
│ │ 每 worker 维护 M 个可复用连接 │
|
||
└───────┼─────────────────────────────────────────────────┘
|
||
│ Unix Domain Socket（每 worker 独立 .sock 文件）
|
||
┌───────▼──────────────┐ ┌──────────────────────────┐
|
||
│ Python 进程 0 │ │ Python 进程 1 │
|
||
│ worker.py │ │ worker.py │
|
||
└──────────────────────┘ └──────────────────────────┘
|
||
```
|
||
|
||
### Python Worker 内部结构
|
||
|
||
```
|
||
Python 进程
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ run() ── UDS server.accept() 循环 │
|
||
│ │ │
|
||
│ 每个连接 → 独立线程 _handle_conn() │
|
||
│ │
|
||
│ ┌─────────────────────────────────────────────────────┐ │
|
||
│ │ _handle_conn（连接线程） │ │
|
||
│ │ │ │
|
||
│ │ ┌──────────────────────────────────────────────┐ │ │
|
||
│ │ │ _ConnMux（单 reader 线程） │ │ │
|
||
│ │ │ │ │ │
|
||
│ │ │ socket ──► 读消息 │ │ │
|
||
│ │ │ │ │ │ │
|
||
│ │ │ ┌────────┼──────────┐ │ │ │
|
||
│ │ │ ▼ ▼ ▼ │ │ │
|
||
│ │ │ call_q chunk_q cancel │ │ │
|
||
│ │ └─────────┬────────┬──────────┼───────────────┘ │ │
|
||
│ │ │ │ │ │ │
|
||
│ │ ▼ │ ▼ │ │
|
||
│ │ 主循环读取 │ PyThreadState_SetAsyncExc │ │
|
||
│ │ _dispatch() │ → 执行线程抛 InterruptedError│ │
|
||
│ │ │ │ │ │
|
||
│ │ ┌──────▼──────┐ │ │ │
|
||
│ │ │ @gobridge fn│ │ │ │
|
||
│ │ │ │ │ │ │
|
||
│ │ │ 普通函数 │ │ │ │
|
||
│ │ │ return val ──────────────► result/error │ │
|
||
│ │ │ │ │ │ │
|
||
│ │ │ 生成器函数 │ │ │ │
|
||
│ │ │ yield val ───────────────► chunk × N │ │
|
||
│ │ │ │ │ + end │ │
|
||
│ │ │ 流式输入 │ │ │ │
|
||
│ │ │ Iterator ◄─┘ │ ← chunk_q │ │
|
||
│ │ └─────────────┘ │ │
|
||
│ └─────────────────────────────────────────────────────┘ │
|
||
└──────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**消息帧：** `[4字节大端长度][JSON载荷]`
|
||
|
||
**消息类型：**
|
||
|
||
| type | 方向 | 含义 |
|
||
|----------|--------------|------------------------------|
|
||
| `call` | Go → Python | 调用请求 |
|
||
| `result` | Python → Go | 普通返回值 |
|
||
| `chunk` | 双向 | 流数据块 |
|
||
| `end` | 双向 | 流结束标记 |
|
||
| `error` | 双向 | 错误响应 |
|
||
| `cancel` | Go → Python | 取消请求，触发 InterruptedError |
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
gobridge/
|
||
├── protocol.go # Message 结构与类型常量
|
||
├── framing.go # 帧读写（4字节长度前缀 + JSON）
|
||
├── worker.go # Python 子进程管理 + UDS 连接池 + 自动重启
|
||
├── pool.go # 多进程池（轮询负载均衡）+ Option 函数
|
||
├── client.go # Invoke[R] 泛型函数（四种模式自动推断）
|
||
├── example/
|
||
│ ├── main.go # 完整调用示例
|
||
│ └── worker.py # Python 函数示例
|
||
└── python/
|
||
└── gobridge/
|
||
└── __init__.py # Python 库（expose、run、_ConnMux）
|
||
```
|
||
|
||
## 类型对应关系
|
||
|
||
| Go 类型 | Python 类型 |
|
||
|-----------|---------------|
|
||
| `int` | `int` |
|
||
| `float64` | `float` |
|
||
| `string` | `str` |
|
||
| `bool` | `bool` |
|
||
| `struct` | `dict` |
|
||
| `[]T` | `list` |
|
||
| `chan T` | `Iterator[T]` |
|
||
|
||
## 参考
|
||
|
||
本项目的进程池、UDS 通信、帧协议设计参考自 [pyproc](https://github.com/YuminosukeSato/pyproc)，在此基础上增加了 Go channel 与 Python yield 的流式对接及 ctx 取消支持。
|