337 lines
12 KiB
Markdown
337 lines
12 KiB
Markdown
---
|
||
name: chongming
|
||
description: >
|
||
用于 chongming-zenoh 项目的开发指导。当用户需要在此项目中添加新 Worker 插件、新增 RPC 端点、
|
||
修改配置驱动路由、开发前端页面、修改工具包、或进行构建部署时，使用此 skill 获取项目架构知识和开发规范。
|
||
keywords:
|
||
- chongming
|
||
- worker
|
||
- plugin
|
||
- rpc_method
|
||
- zenoh
|
||
- fastapi
|
||
- 路由
|
||
- 配置
|
||
- 端点
|
||
- 插件开发
|
||
- 前端
|
||
- Vue
|
||
---
|
||
|
||
# Chongming-Zenoh 项目开发指导
|
||
|
||
## 项目总览
|
||
|
||
Chongming-Zenoh 是一个基于 **FastAPI + Zenoh + Vue 3** 的**配置驱动微服务网关平台**。
|
||
核心理念：通过 TOML 配置文件定义 RPC 端点，自动生成 Pydantic 模型和 FastAPI 路由，
|
||
底层通过 Zenoh 分布式消息协议进行 RPC 通信。
|
||
|
||
### 项目五大部分
|
||
|
||
| 部分 | 路径 | 说明 |
|
||
| --------------------- | -------------------- | -------------------------------------------------------------------------------- |
|
||
| **chongming-core** | `src/chongming/` | 核心应用：FastAPI 工厂、Zenoh 集成、动态路由生成、Worker 管理 |
|
||
| **chongming-web** | `src/chongming-web/` | Vue 3 前端：Element Plus UI、Pinia 状态管理、自动生成的 API 客户端 |
|
||
| **chongming-utils** | `utils/` | 7 个子工具包：config, database, jwt(Rust), lock, password(Rust), request, worker |
|
||
| **chongming-plugins** | `src/plugins/` | Worker 插件：auth, doubao, example，每个插件独立封装业务逻辑 |
|
||
| **chongming-config** | `config/` | 配置文件：Zenoh 配置、Worker 路由 TOML 定义 |
|
||
|
||
## 核心架构与数据流
|
||
|
||
```
|
||
用户请求 → FastAPI 路由（自动生成）→ WorkerManager.call(subject, params)
|
||
→ Zenoh Query → Worker Queryable 回调 → 插件业务逻辑 → 响应
|
||
```
|
||
|
||
### 启动流程
|
||
|
||
```
|
||
serve() → FastAPI lifespan:
|
||
1. setup_nanio() — 本地 S3 子进程
|
||
2. setup_s3() — boto3 S3 客户端
|
||
3. setup_zenoh() — Zenoh peer 会话
|
||
4. setup_worker_manager() — WorkerManager + 定期刷新
|
||
5. load_workers() — 动态 import 插件
|
||
6. register_routes() — 扫描 config/workers/ 生成路由
|
||
```
|
||
|
||
### 关键组件
|
||
|
||
- **`WorkerManager`** (`src/chongming/app/core/worker_manager.py`): Zenoh liveliness 发现 + 本地注册，负载均衡、超时重试、diskcache 缓存
|
||
- **`RouteGenerator`** (`src/chongming/app/core/route_generator.py`): 扫描 `config/workers/<type>/*.toml`，自动生成 FastAPI 端点
|
||
- **`chongming-worker`** (`utils/worker/`): Worker 框架，提供 `@rpc_method` 装饰器、`create_worker()` 运行时
|
||
|
||
---
|
||
|
||
## 开发工作流
|
||
|
||
### 一、添加新的 Worker 插件
|
||
|
||
创建新插件时需要以下步骤：
|
||
|
||
#### 1. 创建插件目录结构
|
||
|
||
```
|
||
src/plugins/<新插件名>/
|
||
├── __init__.py # create_workers() 工厂 + cleanup()
|
||
├── global_var.py # 模块级全局变量
|
||
├── router/ # RPC 端点实现
|
||
│ ├── __init__.py # 从各文件导入，__all__ 导出
|
||
│ └── <操作名>.py # 每个操作一个文件
|
||
└── models/ # 数据模型
|
||
├── __init__.py # 模型导出
|
||
├── pydantic.py # 自动生成（由 gen_models.py）
|
||
└── <表名>.py # SQLModel ORM 模型（如需要）
|
||
```
|
||
|
||
#### 2. 添加 Worker 注册配置
|
||
|
||
在 `config/workers/config.toml` 的 `[[workers]]` 中添加：
|
||
|
||
```toml
|
||
[[workers]]
|
||
type = "<新插件名>"
|
||
module = "plugins.<新插件名>"
|
||
factory = "create_workers"
|
||
cleanup = "cleanup"
|
||
count = 3
|
||
```
|
||
|
||
#### 3. 创建端点 TOML 配置文件
|
||
|
||
`config/workers/<新插件名>/config.toml`:
|
||
|
||
```toml
|
||
[worker]
|
||
defaults.timeout = 30
|
||
defaults.cacheable = false
|
||
|
||
[worker.registration]
|
||
router_prefix = "/<prefix>"
|
||
```
|
||
|
||
`config/workers/<新插件名>/<operation>.toml`:
|
||
|
||
```toml
|
||
[GET] # 或 [POST]
|
||
cacheable = true
|
||
summary = "操作描述"
|
||
params = ["param1: str", "param2: int"] # 仅 GET
|
||
auth_required = false
|
||
|
||
[GET.response_model] # 或 [POST.response_model]
|
||
field_name = { type = "str", required = true }
|
||
another_field = { type = "int", default = 0 }
|
||
```
|
||
|
||
#### 4. 生成 Pydantic 模型
|
||
|
||
```bash
|
||
uv run python -m chongming.scripts.gen_models
|
||
```
|
||
|
||
这会根据 TOML 配置自动生成 `src/plugins/<新插件名>/models/pydantic.py`，包含请求和响应的 Pydantic 模型类。
|
||
|
||
#### 5. 编写 RPC 端点实现 (`router/<操作>.py`)
|
||
|
||
```python
|
||
# src/plugins/<name>/router/<operation>.py
|
||
from chongming_worker.decorators import rpc_method
|
||
from ..models.pydantic import SomeRequest, SomeResponse
|
||
|
||
@rpc_method(subject="<name>.<operation>", method="GET",
|
||
response_model=SomeResponse)
|
||
async def my_operation(request: SomeRequest) -> SomeResponse:
|
||
"""业务逻辑实现"""
|
||
# 使用 global_var 中的资源
|
||
result = await do_something(request)
|
||
return SomeResponse(result=result)
|
||
```
|
||
|
||
**注意**: 此处的 `SomeRequest` / `SomeResponse` 等 Pydantic 模型必须来自步骤 4 生成的 `models/pydantic.py`。编写端点代码前必须先完成模型生成。
|
||
|
||
#### 6. 编写 `router/__init__.py`
|
||
|
||
```python
|
||
# src/plugins/<name>/router/__init__.py
|
||
from . import operation1, operation2
|
||
__all__ = ["operation1", "operation2"]
|
||
```
|
||
|
||
#### 7. 编写 `__init__.py` 工厂函数
|
||
|
||
```python
|
||
# src/plugins/<name>/__init__.py
|
||
from chongming_worker.runtime import create_workers as _create_workers
|
||
|
||
def create_workers(session, config, count, worker_manager):
|
||
"""插件入口：初始化全局资源，创建 Worker 副本"""
|
||
from . import router # 触发 @rpc_method 注册
|
||
from .global_var import set_db, set_client # 设置全局变量
|
||
# 初始化数据库、客户端等...
|
||
_create_workers(session, config, count, worker_manager)
|
||
|
||
async def cleanup(worker_manager):
|
||
"""清理资源"""
|
||
# 关闭连接、清理缓存等...
|
||
```
|
||
|
||
### 二、为现有插件添加新 RPC 端点
|
||
|
||
1. 在 `config/workers/<插件名>/` 下创建 `<新操作>.toml`，定义端点参数和响应模型
|
||
2. 运行 `uv run python -m chongming.scripts.gen_models` 生成 Pydantic 模型
|
||
3. 在 `src/plugins/<插件名>/router/` 下创建 `<新操作>.py`，引用生成的模型编写业务逻辑
|
||
4. 更新 `src/plugins/<插件名>/router/__init__.py`，添加 import
|
||
5. 重启服务
|
||
|
||
### 三、修改配置驱动路由
|
||
|
||
- **修改路由前缀**: 编辑 `config/workers/<插件名>/config.toml` 的 `router_prefix`
|
||
- **添加/修改端点参数**: 编辑 `<操作>.toml`，然后重新生成模型
|
||
- **调整 Worker 副本数**: 编辑 `config/workers/config.toml` 的 `count`
|
||
|
||
### 四、前端开发 (`chongming-web`)
|
||
|
||
位于 `src/chongming-web/`：
|
||
|
||
- **UI 框架**: Element Plus
|
||
- **状态管理**: Pinia
|
||
- **路由**: Vue Router (Hash History)
|
||
- **API 调用**: `src/api/generated/` 中由 `@hey-api/openapi-ts` 自动生成的类型安全客户端
|
||
|
||
添加新页面流程：
|
||
|
||
1. 在 `src/views/` 创建 Vue 组件
|
||
2. 在 `src/router/index.ts` 添加路由
|
||
3. 在 `src/App.vue` 导航菜单添加入口
|
||
4. 如需要，在 `src/api/generated/sdk.gen.ts` 添加或重新生成 API 调用函数
|
||
|
||
### 五、工具包开发 (`chongming-utils`)
|
||
|
||
每个 `utils/<name>/` 下的子包是独立的 Python 包，有各自的 `pyproject.toml`：
|
||
|
||
- **config**: 加载 `config.toml`，TypedDict 配置结构
|
||
- **database**: 异步 SQLite (aiosqlite + SQLModel)
|
||
- **jwt**: Rust 实现的 JWT 编码/验证 (maturin + jsonwebtoken)
|
||
- **lock**: 基于 diskcache 的跨进程分布式锁
|
||
- **password**: Rust 实现的 Argon2id 密码哈希
|
||
- **request**: Zenoh 客户端封装
|
||
- **worker**: Worker 框架核心（`@rpc_method` 装饰器、`create_worker` 运行时）
|
||
|
||
修改工具包后需要重新安装：
|
||
|
||
```bash
|
||
uv pip install -e utils/<name>
|
||
```
|
||
|
||
### 六、编写或更新项目文档 (README.md)
|
||
|
||
项目根目录的 `README.md` 是项目的**主要入口文档**，涵盖项目简介、核心特性、快速上手、构建部署等关键信息。
|
||
当出现以下情况时，应及时同步更新 README：
|
||
|
||
- 新增或移除 Worker 插件
|
||
- 修改项目目录结构或核心配置文件
|
||
- 添加新的环境变量或配置项（如 config.toml 新增字段）
|
||
- 构建流程或打包方式发生变化
|
||
- 快速启动命令或依赖安装方式改变
|
||
- 新增或更新外部依赖（特别是工具包）
|
||
|
||
**推荐结构**（可参考当前 README 模板）：
|
||
|
||
1. **项目名称与描述** – 一句话概括项目定位。
|
||
2. **核心特性** – 列表展示主要功能亮点（如 FastAPI、Zenoh、动态路由、Worker 框架等）。
|
||
3. **项目结构** – 使用树形图展示关键目录与文件的作用。
|
||
4. **快速开始** – 包含依赖安装（推荐 `uv sync`）和启动服务（`uv run serve`）命令。
|
||
5. **构建指南** – 说明 PyInstaller / Nuitka 的打包方式（`uv run build pyinstaller` 等）。
|
||
6. **配置说明** – 指向 `config/` 目录或详细配置文档的链接。
|
||
7. **开发指南** – 可链接到此 Skill（如 `./.agents/skills/chongming/SKILL.md`）供开发者深入阅读。
|
||
|
||
**更新流程：**
|
||
|
||
1. 直接在根目录编辑 `README.md`，保持 Markdown 语法规范。
|
||
2. 验证所有代码示例和命令路径是否正确（可实际执行一次）。
|
||
3. 若新增插件或工具包，在“项目结构”和“核心特性”中体现。
|
||
4. 提交前使用本地预览工具（如 VS Code 的 Markdown 预览）检查排版与链接。
|
||
5. 确保 README 与 `pyproject.toml` 中定义的脚本（`serve`、`gen_models`、`build`）保持一致。
|
||
|
||
> **注意**：README 是项目对外展示的第一窗口，务必保持内容准确、清晰、与代码库同步更新。
|
||
|
||
## 核心约定与规范
|
||
|
||
### 命名约定
|
||
|
||
- **插件名**: 小写下划线，如 `doubao`, `auth`, `example`
|
||
- **操作名**: 小写下划线，如 `analyze`, `add`, `count`
|
||
- **Zenoh subject**: `<插件名>.<操作名>`，如 `example.add`, `doubao.analyze`
|
||
- **TOML 文件名**: 与操作名一致，如 `analyze.toml`, `add.toml`
|
||
- **Python 文件名**: 与操作名一致，如 `analyze.py`, `add.py`
|
||
|
||
### 装饰器使用
|
||
|
||
```python
|
||
@rpc_method(
|
||
subject="plugin.operation", # Zenoh 主题 (必需)
|
||
method="GET", # HTTP 方法: GET 或 POST
|
||
response_model=ResponseCls, # Pydantic 响应模型
|
||
)
|
||
async def handler(request: RequestCls) -> ResponseCls:
|
||
...
|
||
```
|
||
|
||
- GET 端点：参数通过 URL query string 传递，在 TOML 中用 `params` 定义
|
||
- POST 端点：参数通过 JSON body 传递，自动绑定到 Pydantic 请求模型
|
||
|
||
### 全局变量模式
|
||
|
||
每个插件通过 `global_var.py` 管理模块级共享资源：
|
||
|
||
```python
|
||
# global_var.py
|
||
db: Database = None
|
||
|
||
def set_db(database: Database):
|
||
global db
|
||
db = database
|
||
```
|
||
|
||
### TOML 配置字段说明
|
||
|
||
| 字段 | 位置 | 说明 |
|
||
| -------------------- | --------------------- | ---------------------------------- |
|
||
| `count` | `workers/config.toml` | Worker 副本数 |
|
||
| `router_prefix` | `<插件>/config.toml` | API 路由前缀 |
|
||
| `defaults.timeout` | `<插件>/config.toml` | 默认超时 (秒) |
|
||
| `defaults.cacheable` | `<插件>/config.toml` | 是否缓存 RPC 结果 |
|
||
| `params` | `<操作>.toml` `[GET]` | GET 参数列表 (`"name: type"` 格式) |
|
||
| `auth_required` | `<操作>.toml` | 是否需要 JWT 鉴权 |
|
||
| `cacheable` | `<操作>.toml` | 端点是否可缓存 |
|
||
| `summary` | `<操作>.toml` | 端点描述 (用于 OpenAPI docs) |
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
# 开发启动
|
||
uv run serve
|
||
|
||
# 生成 Pydantic 模型
|
||
uv run python -m chongming.scripts.gen_models
|
||
|
||
# 构建
|
||
uv run python -m chongming.scripts.build
|
||
|
||
# 安装/更新工具包子包
|
||
uv pip install -e utils/<name>
|
||
|
||
# 前端开发
|
||
cd src/chongming-web && npm run dev
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **修改 TOML 配置后必须重新生成模型**: `uv run python -m chongming.scripts.gen_models`
|
||
2. **新增插件后需要在 `config/workers/config.toml` 注册**: 否则插件不会被加载
|
||
3. **Rust 工具包 (jwt, password) 需要 maturin**: 通过 `uv run maturin develop --release -m utils/<name>/Cargo.toml` 编译
|
||
4. **插件间隔离**: 每个插件有独立的全局变量，不要跨插件直接引用
|
||
5. **数据库路径约定**: SQLite 数据库文件放在 `data/storage/chongming/` 下
|
||
6. **日志**: 使用标准 `logging.getLogger(__name__)`，核心已配置 ANSI 颜色格式化器
|