chongming-plugins/example/README.md

# Example Worker 插件

演示 `@rpc_method` 装饰器与显式模型绑定的完整用法，是学习开发新插件的**入门参考**。

---

## 实现的功能

### 四则运算（GET / POST）

| 端点 | 方法       | 路径             | 说明                     |
| ---- | ---------- | ---------------- | ------------------------ |
| 加法 | GET / POST | `/calc/add`      | `a + b`                  |
| 减法 | GET        | `/calc/subtract` | `a - b`                  |
| 乘法 | GET        | `/calc/multiply` | `a * b`                  |
| 除法 | GET        | `/calc/divide`   | `a / b`（除数为 0 报错） |

### 访问计数器

| 端点 | 方法 | 路径          | 说明              |
| ---- | ---- | ------------- | ----------------- |
| 计数 | GET  | `/calc/count` | 每次调用计数器 +1 |

基于内存缓存实现，用于演示 GET 端点的无参数调用模式。

---

## 调用示例

```bash
# GET 加法
curl "http://localhost:8000/api/v1/calc/add?a=3&b=4"
# {"result":7.0,"operation":"add","timestamp":1720000000.123}

# POST 加法
curl -X POST "http://localhost:8000/api/v1/calc/add" \
  -H "Content-Type: application/json" \
  -d '{"a": 3.5, "b": 2.5}'
# {"result":6.0,"operation":"add","timestamp":1720000000.456}

# 除法（除数为零）
curl "http://localhost:8000/api/v1/calc/divide?a=10&b=0"
# {"result":0.0,"operation":"divide","error":"Division by zero"}

# 计数器
curl "http://localhost:8000/api/v1/calc/count"
# {"count":1}
```

---

## 如何工作

1. **配置**：`config/workers/example/*.toml` — 定义每个端点的参数和响应结构
2. **模型**：`models/pydantic.py` — 由 `gen_models` 根据 TOML 自动生成
3. **路由**：`router/` 下每个文件实现一个 RPC 端点，使用 `@rpc_method` 装饰器
4. **入口**：`__init__.py` 的 `ExamplePlugin`（Plugin 基类）统一生命周期——`on_init` 初始化
   数据库并发布到 global_var，`create_workers` / `cleanup` 为其 bound method

---

## 开发参考

此插件展示了以下模式：

- GET 端点的 `params` 定义与 `@rpc_method` 参数绑定
- POST 端点的 JSON body 自动解析
- `response_model` 在 TOML 中定义并在装饰器中引用
- 全局变量 (`global_var.py`) 管理共享资源
- 错误处理（如除法除零返回错误信息）
- `auth_required` 控制端点是否需要 JWT 鉴权
- `cacheable` 控制结果是否缓存