Add design documents for HTTP server, router, and WebSocket server
- Created `https-server.md` detailing the HTTP server design, including request normalization, routing, and built-in routes. - Added `router.md` outlining the router system design, core components, and execution flow. - Introduced `ws-server.md` for the WebSocket server design, covering connection handling, message protocols, and custom listener registration.
This commit is contained in:
xiongxiao
452
system_design/https-server.md
Normal file
452
system_design/https-server.md
Normal file
@@ -0,0 +1,452 @@
|
||||
# HTTP Server 设计文档
|
||||
|
||||
## 概述
|
||||
|
||||
HTTP 服务器层负责接收外部 HTTP 请求，将其归一化后传递给 Router 层处理。所有请求统一入口为 `/api/router`。
|
||||
|
||||
## 请求入口
|
||||
|
||||
```
|
||||
POST /api/router?path=demo&key=01
|
||||
GET /api/router?path=demo&key=01
|
||||
```
|
||||
|
||||
| 配置项 | 默认值 | 说明 |
|
||||
|--------|--------|------|
|
||||
| path | /api/router | 请求入口路径 |
|
||||
|
||||
## 请求参数归一化
|
||||
|
||||
HTTP 请求的参数来源于两个部分，最终合并为一个 Message 对象：
|
||||
|
||||
### 1. URL Query (searchParams)
|
||||
|
||||
```typescript
|
||||
// GET /api/router?path=demo&key=01&token=xxx
|
||||
{
|
||||
path: "demo",
|
||||
key: "01",
|
||||
token: "xxx"
|
||||
}
|
||||
```
|
||||
|
||||
### 2. POST Body
|
||||
|
||||
```typescript
|
||||
// POST /api/router
|
||||
// Body: { "name": "test", "value": 123 }
|
||||
{
|
||||
name: "test",
|
||||
value: 123
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 合并规则
|
||||
|
||||
最终的 Message = Query + Body（后者覆盖前者）
|
||||
|
||||
```typescript
|
||||
// GET /api/router?path=demo&key=01
|
||||
// POST Body: { "key": "02", "extra": "data" }
|
||||
{
|
||||
path: "demo",
|
||||
key: "02", // body 覆盖 query
|
||||
extra: "data"
|
||||
}
|
||||
```
|
||||
|
||||
### 4. payload 参数
|
||||
|
||||
如果 query 或 body 中有 `payload` 字段且为 JSON 字符串，会自动解析为对象：
|
||||
|
||||
```typescript
|
||||
// GET /api/router?path=demo&key=01&payload={"id":123}
|
||||
{
|
||||
path: "demo",
|
||||
key: "01",
|
||||
payload: { id: 123 } // 自动解析
|
||||
}
|
||||
```
|
||||
|
||||
### 5. 认证信息
|
||||
|
||||
| 来源 | 字段名 | 说明 |
|
||||
|------|--------|------|
|
||||
| Authorization header | token | Bearer token |
|
||||
| Cookie | token | cookie 中的 token |
|
||||
| Cookie | cookies | 完整 cookie 对象 |
|
||||
|
||||
## 路由匹配
|
||||
|
||||
### 方式一：path + key
|
||||
|
||||
```bash
|
||||
# 访问 path=demo, key=01 的路由
|
||||
POST /api/router?path=demo&key=01
|
||||
```
|
||||
|
||||
### 方式二：id
|
||||
|
||||
```bash
|
||||
# 直接通过路由 ID 访问
|
||||
POST /api/router?id=abc123
|
||||
```
|
||||
|
||||
## 内置路由
|
||||
|
||||
所有内置路由使用统一的访问方式：
|
||||
|
||||
| 路由 | 访问方式 | 说明 |
|
||||
|------|----------|------|
|
||||
| router.list | POST /api/router?path=router&key=list | 获取路由列表 |
|
||||
|
||||
### router.list
|
||||
|
||||
获取当前应用所有路由列表。
|
||||
|
||||
**请求：**
|
||||
|
||||
```bash
|
||||
POST /api/router?path=router&key=list
|
||||
```
|
||||
|
||||
**响应：**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"data": {
|
||||
"list": [
|
||||
{
|
||||
"id": "router$#$list",
|
||||
"path": "router",
|
||||
"key": "list",
|
||||
"description": "列出当前应用下的所有的路由信息",
|
||||
"middleware": [],
|
||||
"metadata": {}
|
||||
}
|
||||
],
|
||||
"isUser": false
|
||||
},
|
||||
"message": "success"
|
||||
}
|
||||
```
|
||||
|
||||
## Go 设计
|
||||
|
||||
```go
|
||||
package server
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"net/http"
|
||||
)
|
||||
|
||||
// Message HTTP 请求归一化后的消息
|
||||
type Message struct {
|
||||
Path string // 路由 path
|
||||
Key string // 路由 key
|
||||
ID string // 路由 ID (优先于 path+key)
|
||||
Token string // 认证 token
|
||||
Payload map[string]interface{} // payload 参数
|
||||
Query url.Values // 原始 query
|
||||
Cookies map[string]string // cookie
|
||||
// 其他参数
|
||||
Extra map[string]interface{}
|
||||
}
|
||||
|
||||
// HandleServer 解析 HTTP 请求
|
||||
func HandleServer(req *http.Request) (*Message, error) {
|
||||
method := req.Method
|
||||
if method != "GET" && method != "POST" {
|
||||
return nil, fmt.Errorf("method not allowed")
|
||||
}
|
||||
|
||||
// 解析 query
|
||||
query := req.URL.Query()
|
||||
|
||||
// 获取 token
|
||||
token := req.Header.Get("Authorization")
|
||||
if token != "" {
|
||||
token = strings.TrimPrefix(token, "Bearer ")
|
||||
}
|
||||
if token == "" {
|
||||
if cookie, err := req.Cookie("token"); err == nil {
|
||||
token = cookie.Value
|
||||
}
|
||||
}
|
||||
|
||||
// 解析 body (POST)
|
||||
var body map[string]interface{}
|
||||
if method == "POST" {
|
||||
if err := json.NewDecoder(req.Body).Decode(&body); err != nil {
|
||||
body = make(map[string]interface{})
|
||||
}
|
||||
}
|
||||
|
||||
// 合并 query 和 body
|
||||
msg := &Message{
|
||||
Token: token,
|
||||
Query: query,
|
||||
Cookies: parseCookies(req.Cookies()),
|
||||
}
|
||||
|
||||
// query 参数
|
||||
if v := query.Get("path"); v != "" {
|
||||
msg.Path = v
|
||||
}
|
||||
if v := query.Get("key"); v != "" {
|
||||
msg.Key = v
|
||||
}
|
||||
if v := query.Get("id"); v != "" {
|
||||
msg.ID = v
|
||||
}
|
||||
if v := query.Get("payload"); v != "" {
|
||||
if err := json.Unmarshal([]byte(v), &msg.Payload); err == nil {
|
||||
// payload 解析成功
|
||||
}
|
||||
}
|
||||
|
||||
// body 参数覆盖 query
|
||||
for k, v := range body {
|
||||
msg.Extra[k] = v
|
||||
switch k {
|
||||
case "path":
|
||||
msg.Path = v.(string)
|
||||
case "key":
|
||||
msg.Key = v.(string)
|
||||
case "id":
|
||||
msg.ID = v.(string)
|
||||
case "payload":
|
||||
msg.Payload = v.(map[string]interface{})
|
||||
}
|
||||
}
|
||||
|
||||
return msg, nil
|
||||
}
|
||||
|
||||
// RouterHandler 创建 HTTP 处理函数
|
||||
func RouterHandler(router *QueryRouter) http.HandlerFunc {
|
||||
return func(w http.ResponseWriter, req *http.Request) {
|
||||
// CORS
|
||||
w.Header().Set("Access-Control-Allow-Origin", "*")
|
||||
w.Header().Set("Access-Control-Allow-Methods", "GET, POST")
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
|
||||
if req.Method == "OPTIONS" {
|
||||
w.WriteHeader(http.StatusOK)
|
||||
return
|
||||
}
|
||||
|
||||
msg, err := HandleServer(req)
|
||||
if err != nil {
|
||||
json.NewEncoder(w).Encode(Result{Code: 400, Message: err.Error()})
|
||||
return
|
||||
}
|
||||
|
||||
// 调用 router.run
|
||||
result, err := router.Run(*msg, nil)
|
||||
if err != nil {
|
||||
json.NewEncoder(w).Encode(Result{Code: 500, Message: err.Error()})
|
||||
return
|
||||
}
|
||||
|
||||
json.NewEncoder(w).Encode(result)
|
||||
}
|
||||
}
|
||||
|
||||
// Server HTTP 服务器
|
||||
type Server struct {
|
||||
Router *QueryRouter
|
||||
Path string
|
||||
Handlers []http.HandlerFunc
|
||||
}
|
||||
|
||||
func (s *Server) Listen(addr string) error {
|
||||
mux := http.NewServeMux()
|
||||
|
||||
// 自定义处理器
|
||||
for _, h := range s.Handlers {
|
||||
mux.HandleFunc(s.Path, h)
|
||||
}
|
||||
|
||||
// 路由处理器
|
||||
mux.HandleFunc(s.Path, RouterHandler(s.Router))
|
||||
|
||||
return http.ListenAndServe(addr, mux)
|
||||
}
|
||||
```
|
||||
|
||||
## Rust 设计
|
||||
|
||||
```rust
|
||||
use actix_web::{web, App, HttpServer, HttpRequest, HttpResponse, Responder};
|
||||
use serde::{Deserialize, Serialize};
|
||||
use std::collections::HashMap;
|
||||
|
||||
// Message HTTP 请求归一化后的消息
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct Message {
|
||||
pub path: Option<String>,
|
||||
pub key: Option<String>,
|
||||
pub id: Option<String>,
|
||||
pub token: Option<String>,
|
||||
pub payload: Option<HashMap<String, Value>>,
|
||||
#[serde(flatten)]
|
||||
pub extra: HashMap<String, Value>,
|
||||
}
|
||||
|
||||
// Result 调用结果
|
||||
#[derive(Debug, Serialize)]
|
||||
pub struct Result {
|
||||
pub code: i32,
|
||||
pub data: Option<Value>,
|
||||
pub message: Option<String>,
|
||||
}
|
||||
|
||||
// 解析 HTTP 请求
|
||||
pub async fn handle_server(req: HttpRequest, body: web::Bytes) -> Result<Message, String> {
|
||||
let method = req.method().as_str();
|
||||
if method != "GET" && method != "POST" {
|
||||
return Err("method not allowed".to_string());
|
||||
}
|
||||
|
||||
// 获取 query 参数
|
||||
let query: web::Query<HashMap<String, String>> = web::Query::clone(&req);
|
||||
|
||||
// 获取 token
|
||||
let mut token = None;
|
||||
if let Some(auth) = req.headers().get("authorization") {
|
||||
if let Ok(s) = auth.to_str() {
|
||||
token = Some(s.trim_start_matches("Bearer ").to_string());
|
||||
}
|
||||
}
|
||||
if token.is_none() {
|
||||
if let Some(cookie) = req.cookie("token") {
|
||||
token = Some(cookie.value().to_string());
|
||||
}
|
||||
}
|
||||
|
||||
// 解析 body (POST)
|
||||
let mut body_map = HashMap::new();
|
||||
if method == "POST" {
|
||||
if let Ok(v) = serde_json::from_slice::<Value>(&body) {
|
||||
if let Some(obj) = v.as_object() {
|
||||
for (k, val) in obj {
|
||||
body_map.insert(k.clone(), val.clone());
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 构建 Message
|
||||
let mut msg = Message {
|
||||
path: query.get("path").cloned(),
|
||||
key: query.get("key").cloned(),
|
||||
id: query.get("id").cloned(),
|
||||
token,
|
||||
payload: None,
|
||||
extra: HashMap::new(),
|
||||
};
|
||||
|
||||
// 处理 payload
|
||||
if let Some(p) = query.get("payload") {
|
||||
if let Ok(v) = serde_json::from_str::<Value>(p) {
|
||||
msg.payload = v.as_object().map(|m| m.clone());
|
||||
}
|
||||
}
|
||||
|
||||
// body 覆盖 query
|
||||
for (k, v) in body_map {
|
||||
match k.as_str() {
|
||||
"path" => msg.path = v.as_str().map(|s| s.to_string()),
|
||||
"key" => msg.key = v.as_str().map(|s| s.to_string()),
|
||||
"id" => msg.id = v.as_str().map(|s| s.to_string()),
|
||||
"payload" => msg.payload = v.as_object().map(|m| m.clone()),
|
||||
_ => msg.extra.insert(k, v),
|
||||
}
|
||||
}
|
||||
|
||||
Ok(msg)
|
||||
}
|
||||
|
||||
// HTTP 处理函数
|
||||
async fn router_handler(
|
||||
req: HttpRequest,
|
||||
body: web::Bytes,
|
||||
router: web::Data<QueryRouter>,
|
||||
) -> impl Responder {
|
||||
let msg = match handle_server(req, body).await {
|
||||
Ok(m) => m,
|
||||
Err(e) => return HttpResponse::BadRequest().json(Result {
|
||||
code: 400,
|
||||
data: None,
|
||||
message: Some(e),
|
||||
}),
|
||||
};
|
||||
|
||||
// 调用 router.run
|
||||
match router.run(msg, None).await {
|
||||
Ok(result) => HttpResponse::Ok().json(result),
|
||||
Err(e) => HttpResponse::InternalServerError().json(Result {
|
||||
code: 500,
|
||||
data: None,
|
||||
message: Some(e.to_string()),
|
||||
}),
|
||||
}
|
||||
}
|
||||
|
||||
// Server HTTP 服务器
|
||||
pub struct Server {
|
||||
pub router: QueryRouter,
|
||||
pub path: String,
|
||||
}
|
||||
|
||||
impl Server {
|
||||
pub async fn listen(self, addr: &str) -> std::io::Result<()> {
|
||||
let router = web::Data::new(self.router);
|
||||
|
||||
HttpServer::new(move || {
|
||||
App::new()
|
||||
.app_data(router.clone())
|
||||
.route(&self.path, web::post().to(router_handler))
|
||||
.route(&self.path, web::get().to(router_handler))
|
||||
})
|
||||
.bind(addr)?
|
||||
.run()
|
||||
.await
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 请求示例
|
||||
|
||||
### 基础请求
|
||||
|
||||
```bash
|
||||
# 访问 demo/01 路由
|
||||
curl -X POST "http://localhost:4002/api/router?path=demo&key=01"
|
||||
|
||||
# 带 body
|
||||
curl -X POST "http://localhost:4002/api/router?path=demo&key=01" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name":"test","value":123}'
|
||||
```
|
||||
|
||||
### 获取路由列表
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:4002/api/router?path=router&key=list"
|
||||
```
|
||||
|
||||
### 带认证
|
||||
|
||||
```bash
|
||||
# 通过 Header
|
||||
curl -X POST "http://localhost:4002/api/router?path=demo&key=01" \
|
||||
-H "Authorization: Bearer your-token"
|
||||
|
||||
# 通过 Cookie
|
||||
curl -X POST "http://localhost:4002/api/router?path=demo&key=01" \
|
||||
-b "token=your-token"
|
||||
```
|
||||
378
system_design/router.md
Normal file
378
system_design/router.md
Normal file
@@ -0,0 +1,378 @@
|
||||
# Router 系统设计文档
|
||||
|
||||
## 概述
|
||||
|
||||
轻量级路由框架，支持链式路由、中间件模式、统一上下文。适用于构建 API 服务，支持跨语言实现（Go、Rust 等）。
|
||||
|
||||
## 核心组件
|
||||
|
||||
### Route
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| path | string | 一级路径 |
|
||||
| key | string | 二级路径 |
|
||||
| id | string | 唯一标识 |
|
||||
| run | Handler | 业务处理函数 |
|
||||
| nextRoute | NextRoute? | 下一个路由 |
|
||||
| middleware | string[] | 中间件 ID 列表 |
|
||||
| metadata | T | 元数据/参数 schema |
|
||||
| type | string | 类型：route / middleware |
|
||||
| isDebug | bool | 是否开启调试 |
|
||||
|
||||
### NextRoute
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | string? | 路由 ID |
|
||||
| path | string? | 一级路径 |
|
||||
| key | string? | 二级路径 |
|
||||
|
||||
### RouteContext
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| appId | string? | 应用 ID |
|
||||
| query | object | URL 参数和 payload 合并结果 |
|
||||
| args | object | 同 query |
|
||||
| body | any | 响应 body |
|
||||
| code | number | 响应状态码 |
|
||||
| message | string | 响应消息 |
|
||||
| state | object | 状态传递 |
|
||||
| currentId | string? | 当前路由 ID |
|
||||
| currentPath | string? | 当前路径 |
|
||||
| currentKey | string? | 当前 key |
|
||||
| currentRoute | Route? | 当前路由对象 |
|
||||
| progress | [string, string][] | 路由执行路径 |
|
||||
| nextQuery | object | 传递给下一个路由的参数 |
|
||||
| end | boolean | 是否提前结束 |
|
||||
| app | QueryRouter? | 路由实例引用 |
|
||||
| error | any | 错误信息 |
|
||||
| call | function | 调用其他路由（返回完整上下文） |
|
||||
| run | function | 调用其他路由（返回简化结果） |
|
||||
| throw | function | 抛出错误 |
|
||||
| needSerialize | boolean | 是否需要序列化 |
|
||||
|
||||
### QueryRouter
|
||||
|
||||
| 方法 | 说明 |
|
||||
|------|------|
|
||||
| add(route, opts?) | 添加路由 |
|
||||
| remove(route) | 按 path/key 移除路由 |
|
||||
| removeById(id) | 按 ID 移除路由 |
|
||||
| runRoute(path, key, ctx) | 执行单个路由 |
|
||||
| parse(message, ctx) | 入口解析，返回完整上下文 |
|
||||
| call(message, ctx) | 调用路由，返回完整上下文 |
|
||||
| run(message, ctx) | 调用路由，返回简化结果 {code, data, message} |
|
||||
| getHandle() | 获取 HTTP 处理函数 |
|
||||
| setContext(ctx) | 设置默认上下文 |
|
||||
| getList(filter?) | 获取路由列表 |
|
||||
| hasRoute(path, key) | 检查路由是否存在 |
|
||||
| findRoute(opts) | 查找路由 |
|
||||
| exportRoutes() | 导出所有路由 |
|
||||
| importRoutes(routes) | 批量导入路由 |
|
||||
| createRouteList(opts) | 创建内置的路由列表功能 |
|
||||
|
||||
### QueryRouterServer
|
||||
|
||||
继承 QueryRouter，新增：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| appId | string | 应用 ID |
|
||||
| handle | function | HTTP 处理函数 |
|
||||
|
||||
| 方法 | 说明 |
|
||||
|------|------|
|
||||
| setHandle(wrapperFn, ctx) | 设置处理函数 |
|
||||
| route(path, key?, opts?) | 工厂方法创建路由 |
|
||||
|
||||
## Go 设计
|
||||
|
||||
```go
|
||||
package router
|
||||
|
||||
// Route 路由单元
|
||||
type Route struct {
|
||||
Path string
|
||||
Key string
|
||||
ID string
|
||||
Run func(ctx *RouteContext) (*RouteContext, error)
|
||||
NextRoute *NextRoute
|
||||
Middleware []string
|
||||
Metadata map[string]interface{}
|
||||
Type string
|
||||
IsDebug bool
|
||||
}
|
||||
|
||||
// NextRoute 下一个路由
|
||||
type NextRoute struct {
|
||||
ID string
|
||||
Path string
|
||||
Key string
|
||||
}
|
||||
|
||||
// RouteContext 请求上下文
|
||||
type RouteContext struct {
|
||||
AppID string
|
||||
Query map[string]interface{}
|
||||
Args map[string]interface{}
|
||||
Body interface{}
|
||||
Code int
|
||||
Message string
|
||||
State map[string]interface{}
|
||||
CurrentID string
|
||||
CurrentPath string
|
||||
CurrentKey string
|
||||
CurrentRoute *Route
|
||||
Progress [][2]string
|
||||
NextQuery map[string]interface{}
|
||||
End bool
|
||||
App *QueryRouter
|
||||
Error error
|
||||
NeedSerialize bool
|
||||
// Methods
|
||||
Call func(msg interface{}, ctx *RouteContext) (*RouteContext, error)
|
||||
Run func(msg interface{}, ctx *RouteContext) (interface{}, error)
|
||||
Throw func(err interface{})
|
||||
}
|
||||
|
||||
// Message 调用消息
|
||||
type Message struct {
|
||||
ID string
|
||||
Path string
|
||||
Key string
|
||||
Payload map[string]interface{}
|
||||
}
|
||||
|
||||
// Result 调用结果
|
||||
type Result struct {
|
||||
Code int
|
||||
Data interface{}
|
||||
Message string
|
||||
}
|
||||
|
||||
// AddOpts 添加选项
|
||||
type AddOpts struct {
|
||||
Overwrite bool
|
||||
}
|
||||
|
||||
// QueryRouter 路由管理器
|
||||
type QueryRouter struct {
|
||||
Routes []*Route
|
||||
MaxNextRoute int
|
||||
Context *RouteContext
|
||||
}
|
||||
|
||||
func NewQueryRouter() *QueryRouter
|
||||
|
||||
func (r *QueryRouter) Add(route *Route, opts *AddOpts)
|
||||
func (r *QueryRouter) Remove(path, key string)
|
||||
func (r *QueryRouter) RemoveByID(id string)
|
||||
func (r *QueryRouter) RunRoute(path, key string, ctx *RouteContext) (*RouteContext, error)
|
||||
func (r *QueryRouter) Parse(msg Message, ctx *RouteContext) (*RouteContext, error)
|
||||
func (r *QueryRouter) Call(msg Message, ctx *RouteContext) (*RouteContext, error)
|
||||
func (r *QueryRouter) Run(msg Message, ctx *RouteContext) (Result, error)
|
||||
func (r *QueryRouter) GetHandle() func(msg interface{}) Result
|
||||
func (r *QueryRouter) SetContext(ctx *RouteContext)
|
||||
func (r *QueryRouter) GetList() []Route
|
||||
func (r *QueryRouter) HasRoute(path, key string) bool
|
||||
func (r *QueryRouter) FindRoute(opts FindOpts) *Route
|
||||
|
||||
// QueryRouterServer 服务端
|
||||
type QueryRouterServer struct {
|
||||
QueryRouter
|
||||
AppID string
|
||||
Handle func(msg interface{}) Result
|
||||
}
|
||||
|
||||
type ServerOpts struct {
|
||||
HandleFn func(msg interface{}, ctx interface{}) Result
|
||||
Context *RouteContext
|
||||
AppID string
|
||||
}
|
||||
|
||||
func NewQueryRouterServer(opts *ServerOpts) *QueryRouterServer
|
||||
|
||||
func (s *QueryRouterServer) SetHandle(wrapperFn func(msg interface{}, ctx interface{}) Result, ctx *RouteContext)
|
||||
func (s *QueryRouterServer) Route(path string, key ...string) *Route
|
||||
```
|
||||
|
||||
## Rust 设计
|
||||
|
||||
```rust
|
||||
use std::collections::HashMap;
|
||||
use std::future::Future;
|
||||
use std::pin::Pin;
|
||||
|
||||
// Route 路由单元
|
||||
pub struct Route<M = Value> {
|
||||
pub path: String,
|
||||
pub key: String,
|
||||
pub id: String,
|
||||
pub run: Option<Box<dyn Fn(RouteContext) -> Pin<Box<dyn Future<Output = Result<RouteContext>>>> + Send>>,
|
||||
pub next_route: Option<NextRoute>,
|
||||
pub middleware: Vec<String>,
|
||||
pub metadata: M,
|
||||
pub route_type: String,
|
||||
pub is_debug: bool,
|
||||
}
|
||||
|
||||
// NextRoute 下一个路由
|
||||
#[derive(Clone)]
|
||||
pub struct NextRoute {
|
||||
pub id: Option<String>,
|
||||
pub path: Option<String>,
|
||||
pub key: Option<String>,
|
||||
}
|
||||
|
||||
// RouteContext 请求上下文
|
||||
#[derive(Clone)]
|
||||
pub struct RouteContext {
|
||||
pub app_id: Option<String>,
|
||||
pub query: HashMap<String, Value>,
|
||||
pub args: HashMap<String, Value>,
|
||||
pub body: Option<Value>,
|
||||
pub code: Option<i32>,
|
||||
pub message: Option<String>,
|
||||
pub state: HashMap<String, Value>,
|
||||
pub current_id: Option<String>,
|
||||
pub current_path: Option<String>,
|
||||
pub current_key: Option<String>,
|
||||
pub current_route: Option<Box<Route>>,
|
||||
pub progress: Vec<(String, String)>,
|
||||
pub next_query: HashMap<String, Value>,
|
||||
pub end: bool,
|
||||
pub app: Option<Box<QueryRouter>>,
|
||||
pub error: Option<Value>,
|
||||
pub need_serialize: bool,
|
||||
}
|
||||
|
||||
// Message 调用消息
|
||||
#[derive(Clone)]
|
||||
pub struct Message {
|
||||
pub id: Option<String>,
|
||||
pub path: Option<String>,
|
||||
pub key: Option<String>,
|
||||
pub payload: HashMap<String, Value>,
|
||||
}
|
||||
|
||||
// Result 调用结果
|
||||
pub struct Result {
|
||||
pub code: i32,
|
||||
pub data: Option<Value>,
|
||||
pub message: Option<String>,
|
||||
}
|
||||
|
||||
// AddOpts 添加选项
|
||||
pub struct AddOpts {
|
||||
pub overwrite: bool,
|
||||
}
|
||||
|
||||
// FindOpts 查找选项
|
||||
pub struct FindOpts {
|
||||
pub path: Option<String>,
|
||||
pub key: Option<String>,
|
||||
pub id: Option<String>,
|
||||
}
|
||||
|
||||
// QueryRouter 路由管理器
|
||||
pub struct QueryRouter {
|
||||
pub routes: Vec<Route>,
|
||||
pub max_next_route: usize,
|
||||
pub context: RouteContext,
|
||||
}
|
||||
|
||||
impl QueryRouter {
|
||||
pub fn new() -> Self
|
||||
pub fn add(&mut self, route: Route, opts: Option<AddOpts>)
|
||||
pub fn remove(&mut self, path: &str, key: &str)
|
||||
pub fn remove_by_id(&mut self, id: &str)
|
||||
pub async fn run_route(&self, path: &str, key: &str, ctx: RouteContext) -> Result<RouteContext>
|
||||
pub async fn parse(&self, msg: Message, ctx: Option<RouteContext>) -> Result<RouteContext>
|
||||
pub async fn call(&self, msg: Message, ctx: Option<RouteContext>) -> Result<RouteContext>
|
||||
pub async fn run(&self, msg: Message, ctx: Option<RouteContext>) -> Result<Result>
|
||||
pub fn get_handle(&self) -> impl Fn(Message) -> Result + '_
|
||||
pub fn set_context(&mut self, ctx: RouteContext)
|
||||
pub fn get_list(&self) -> Vec<Route>
|
||||
pub fn has_route(&self, path: &str, key: &str) -> bool
|
||||
pub fn find_route(&self, opts: FindOpts) -> Option<&Route>
|
||||
}
|
||||
|
||||
// ServerOpts 服务端选项
|
||||
pub struct ServerOpts {
|
||||
pub handle_fn: Option<Box<dyn Fn(Message, Option<RouteContext>) -> Result + Send>>,
|
||||
pub context: Option<RouteContext>,
|
||||
pub app_id: Option<String>,
|
||||
}
|
||||
|
||||
// QueryRouterServer 服务端
|
||||
pub struct QueryRouterServer {
|
||||
pub router: QueryRouter,
|
||||
pub app_id: String,
|
||||
pub handle: Option<Box<dyn Fn(Message) -> Result + Send>>,
|
||||
}
|
||||
|
||||
impl QueryRouterServer {
|
||||
pub fn new(opts: Option<ServerOpts>) -> Self
|
||||
pub fn set_handle(&mut self, wrapperFn: Box<dyn Fn(Message) -> Result + Send>)
|
||||
pub fn route(&self, path: &str, key: Option<&str>) -> Route
|
||||
}
|
||||
```
|
||||
|
||||
## 执行流程
|
||||
|
||||
```
|
||||
Message → parse() → runRoute() → [middleware] → run() → [nextRoute] → ...
|
||||
↓
|
||||
RouteContext (层层传递)
|
||||
```
|
||||
|
||||
1. `parse()` 接收消息，初始化上下文（query、args、state）
|
||||
2. `runRoute()` 查找路由，先执行 middleware，再执行 run
|
||||
3. middleware 执行出错立即返回错误
|
||||
4. 如有 nextRoute，递归执行下一个路由（最多 40 层）
|
||||
5. 返回最终 RouteContext
|
||||
|
||||
## 特性说明
|
||||
|
||||
- **双层路径**: path + key 构成唯一路由
|
||||
- **链式路由**: nextRoute 支持路由链式执行
|
||||
- **中间件**: 每个 Route 可挂载多个 middleware
|
||||
- **统一上下文**: RouteContext 贯穿整个请求生命周期
|
||||
|
||||
## 内置路由
|
||||
|
||||
框架内置以下路由，通过 HTTP 访问时使用 `path` 和 `key` 参数：
|
||||
|
||||
| 路由 path | 路由 key | 说明 |
|
||||
|-----------|----------|------|
|
||||
| router | list | 获取当前应用所有路由列表 |
|
||||
|
||||
### router/list
|
||||
|
||||
获取当前应用所有路由列表。
|
||||
|
||||
**访问方式：** `POST /api/router?path=router&key=list`
|
||||
|
||||
**响应：**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"data": {
|
||||
"list": [
|
||||
{
|
||||
"id": "router$#$list",
|
||||
"path": "router",
|
||||
"key": "list",
|
||||
"description": "列出当前应用下的所有的路由信息",
|
||||
"middleware": [],
|
||||
"metadata": {}
|
||||
}
|
||||
],
|
||||
"isUser": false
|
||||
},
|
||||
"message": "success"
|
||||
}
|
||||
```
|
||||
421
system_design/ws-server.md
Normal file
421
system_design/ws-server.md
Normal file
@@ -0,0 +1,421 @@
|
||||
# WebSocket Server 设计文档
|
||||
|
||||
## 概述
|
||||
|
||||
WebSocket 服务器支持实时双向通信，可与 HTTP 服务器共享同一端口。所有 WebSocket 连接统一入口为 `/api/router`，通过 `type` 参数区分业务类型。
|
||||
|
||||
## 连接入口
|
||||
|
||||
```
|
||||
ws://host:port/api/router?token=xxx&id=client-id
|
||||
```
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| token | 认证 token |
|
||||
| id | 客户端标识 |
|
||||
|
||||
## 消息协议
|
||||
|
||||
### 请求消息格式
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "router",
|
||||
"path": "demo",
|
||||
"key": "01",
|
||||
"payload": { "name": "test" }
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| type | string | 消息类型：router |
|
||||
| path | string | 路由 path |
|
||||
| key | string | 路由 key |
|
||||
| payload | object | 请求参数 |
|
||||
|
||||
### 响应消息格式
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "router",
|
||||
"code": 200,
|
||||
"data": { "result": "success" },
|
||||
"message": "success"
|
||||
}
|
||||
```
|
||||
|
||||
### 内置消息类型
|
||||
|
||||
| 消息 | 说明 |
|
||||
|------|------|
|
||||
| ping | 服务端返回 pong |
|
||||
| close | 关闭连接 |
|
||||
| connected | 连接成功通知 |
|
||||
|
||||
## 自定义 WebSocket 监听器
|
||||
|
||||
可以注册自定义的 WebSocket 监听器来处理特定路径的 WebSocket 连接。
|
||||
|
||||
### 注册监听器
|
||||
|
||||
```typescript
|
||||
app.on([
|
||||
{
|
||||
path: '/ws/chat',
|
||||
io: true,
|
||||
func: async (req, res) => {
|
||||
const { data, token, pathname, id, ws, emitter } = req;
|
||||
// 处理聊天消息
|
||||
res.end({ message: 'received' });
|
||||
}
|
||||
}
|
||||
]);
|
||||
```
|
||||
|
||||
### Listener 配置
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| path | string | WebSocket 路径 |
|
||||
| io | boolean | 是否为 WebSocket 监听器 |
|
||||
| func | function | 处理函数 |
|
||||
| json | boolean | 是否自动解析 JSON |
|
||||
|
||||
## 执行流程
|
||||
|
||||
```
|
||||
WebSocket 连接 → 查找 listener → 自定义处理 / 默认 router 处理 → 响应
|
||||
```
|
||||
|
||||
1. WebSocket 连接建立时，解析 URL 获取 pathname、token、id
|
||||
2. 查找是否有匹配的自定义 listener
|
||||
3. 如有自定义 listener，调用对应处理函数
|
||||
4. 如无自定义 listener，使用默认处理：
|
||||
- type = 'router' 时，调用 handle 处理路由
|
||||
- 支持 ping/pong/close 内置命令
|
||||
5. 响应消息通过 ws.send 返回
|
||||
|
||||
## Go 设计
|
||||
|
||||
```go
|
||||
package server
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"net/http"
|
||||
|
||||
"github.com/gorilla/websocket"
|
||||
)
|
||||
|
||||
// WebSocketMessage WebSocket 消息
|
||||
type WebSocketMessage struct {
|
||||
Type string `json:"type"`
|
||||
Path string `json:"path,omitempty"`
|
||||
Key string `json:"key,omitempty"`
|
||||
Payload map[string]interface{} `json:"payload,omitempty"`
|
||||
Data interface{} `json:"data,omitempty"`
|
||||
Code int `json:"code,omitempty"`
|
||||
Message string `json:"message,omitempty"`
|
||||
}
|
||||
|
||||
// WebSocketUpgrader WebSocket 升级配置
|
||||
var upgrader = websocket.Upgrader{
|
||||
CheckOrigin: func(r *http.Request) bool {
|
||||
return true
|
||||
},
|
||||
}
|
||||
|
||||
// Listener WebSocket 监听器
|
||||
type Listener struct {
|
||||
Path string
|
||||
IO bool
|
||||
Func func(msg WebSocketMessage, ws *websocket.Conn) error
|
||||
JSON bool
|
||||
}
|
||||
|
||||
// WsServer WebSocket 服务器
|
||||
type WsServer struct {
|
||||
Router *QueryRouter
|
||||
Path string
|
||||
Listeners []Listener
|
||||
Listen func() error
|
||||
}
|
||||
|
||||
// HandleWebSocket 处理 WebSocket 连接
|
||||
func (s *WsServer) HandleWebSocket(w http.ResponseWriter, r *http.Request) {
|
||||
ws, err := upgrader.Upgrade(w, r, nil)
|
||||
if err != nil {
|
||||
return
|
||||
}
|
||||
defer ws.Close()
|
||||
|
||||
// 解析 token 和 id
|
||||
token := r.URL.Query().Get("token")
|
||||
id := r.URL.Query().Get("id")
|
||||
|
||||
for {
|
||||
// 读取消息
|
||||
_, msgBytes, err := ws.ReadMessage()
|
||||
if err != nil {
|
||||
break
|
||||
}
|
||||
|
||||
var msg WebSocketMessage
|
||||
if err := json.Unmarshal(msgBytes, &msg); err != nil {
|
||||
ws.WriteJSON(WebSocketMessage{
|
||||
Code: 400,
|
||||
Message: "invalid message",
|
||||
})
|
||||
continue
|
||||
}
|
||||
|
||||
// 查找自定义 listener
|
||||
pathname := r.URL.Path
|
||||
var handled bool
|
||||
for _, listener := range s.Listeners {
|
||||
if listener.IO && listener.Path == pathname {
|
||||
if err := listener.Func(msg, ws); err != nil {
|
||||
ws.WriteJSON(WebSocketMessage{
|
||||
Code: 500,
|
||||
Message: err.Error(),
|
||||
})
|
||||
}
|
||||
handled = true
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
if handled {
|
||||
continue
|
||||
}
|
||||
|
||||
// 默认处理：router 类型
|
||||
if msg.Type == "router" {
|
||||
result, err := s.Router.Run(Message{
|
||||
Path: msg.Path,
|
||||
Key: msg.Key,
|
||||
Payload: msg.Payload,
|
||||
}, nil)
|
||||
if err != nil {
|
||||
ws.WriteJSON(WebSocketMessage{
|
||||
Code: 500,
|
||||
Message: err.Error(),
|
||||
})
|
||||
continue
|
||||
}
|
||||
ws.WriteJSON(WebSocketMessage{
|
||||
Type: "router",
|
||||
Code: result.Code,
|
||||
Data: result.Data,
|
||||
Message: result.Message,
|
||||
})
|
||||
continue
|
||||
}
|
||||
|
||||
// 内置命令
|
||||
if string(msgBytes) == "ping" {
|
||||
ws.WriteMessage(websocket.TextMessage, []byte("pong"))
|
||||
continue
|
||||
}
|
||||
|
||||
if string(msgBytes) == "close" {
|
||||
break
|
||||
}
|
||||
|
||||
ws.WriteJSON(WebSocketMessage{
|
||||
Code: 400,
|
||||
Message: "unknown type",
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// Start 启动服务器
|
||||
func (s *WsServer) Start(addr string) error {
|
||||
http.HandleFunc(s.Path, s.HandleWebSocket)
|
||||
return http.ListenAndServe(addr, nil)
|
||||
}
|
||||
```
|
||||
|
||||
## Rust 设计
|
||||
|
||||
```rust
|
||||
use actix_web::{web, App, HttpServer, HttpRequest, HttpResponse, Responder};
|
||||
use actix_ws::{Message, Session, Aggregate};
|
||||
use std::sync::Arc;
|
||||
|
||||
// WebSocket 消息
|
||||
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
|
||||
pub struct WsMessage {
|
||||
pub r#type: Option<String>,
|
||||
pub path: Option<String>,
|
||||
pub key: Option<String>,
|
||||
pub payload: Option<serde_json::Value>,
|
||||
pub data: Option<serde_json::Value>,
|
||||
pub code: Option<i32>,
|
||||
pub message: Option<String>,
|
||||
}
|
||||
|
||||
// Listener 配置
|
||||
pub struct Listener {
|
||||
pub path: String,
|
||||
pub io: bool,
|
||||
pub func: Option<Box<dyn Fn(WsMessage, &mut Session) -> Result<(), Box<dyn std::error::Error>> + Send>>,
|
||||
pub json: bool,
|
||||
}
|
||||
|
||||
// WsServer
|
||||
pub struct WsServer {
|
||||
pub router: QueryRouter,
|
||||
pub path: String,
|
||||
pub listeners: Vec<Listener>,
|
||||
}
|
||||
|
||||
impl WsServer {
|
||||
pub async fn start(&self, addr: &str) -> std::io::Result<()> {
|
||||
let router = web::Data::new(self.router.clone());
|
||||
let path = self.path.clone();
|
||||
|
||||
HttpServer::new(move || {
|
||||
App::new()
|
||||
.app_data(router.clone())
|
||||
.service(
|
||||
web::resource(&path)
|
||||
.route(web::get().to(ws_handler))
|
||||
)
|
||||
})
|
||||
.bind(addr)?
|
||||
.run()
|
||||
.await
|
||||
}
|
||||
}
|
||||
|
||||
async fn ws_handler(
|
||||
req: HttpRequest,
|
||||
stream: web::Payload,
|
||||
router: web::Data<QueryRouter>,
|
||||
) -> impl Responder {
|
||||
let (resp, session, msg) = actix_ws::handle(&req, stream)?;
|
||||
|
||||
let mut session = session;
|
||||
|
||||
// 处理消息
|
||||
while let Some(result) = msg.next().await {
|
||||
match result {
|
||||
Ok(Message::Text(text)) => {
|
||||
let ws_msg: WsMessage = match serde_json::from_str(&text) {
|
||||
Ok(m) => m,
|
||||
Err(_) => {
|
||||
let _ = session.text(r#"{"code":400,"message":"invalid message"}"#).await;
|
||||
continue;
|
||||
}
|
||||
};
|
||||
|
||||
// 调用 router
|
||||
if ws_msg.r#type.as_deref() == Some("router") {
|
||||
let msg = Message {
|
||||
path: ws_msg.path.clone(),
|
||||
key: ws_msg.key.clone(),
|
||||
payload: ws_msg.payload.clone(),
|
||||
};
|
||||
|
||||
match router.run(msg, None).await {
|
||||
Ok(result) => {
|
||||
let resp = WsMessage {
|
||||
r Some("router".to_string()),
|
||||
code: Some(result.code),
|
||||
data: result.data,
|
||||
message: result.message,
|
||||
};
|
||||
let _ = session.text(serde_json::to_string(&resp).unwrap()).await;
|
||||
}
|
||||
Err(e) => {
|
||||
let _ = session.text(format!(r#"{{"code":500,"message":"{}"}}"#, e)).await;
|
||||
}
|
||||
}
|
||||
} else if text == "ping" {
|
||||
let _ = session.text("pong").await;
|
||||
} else if text == "close" {
|
||||
break;
|
||||
}
|
||||
}
|
||||
Ok(Message::Close(_)) => break,
|
||||
Err(e) => {
|
||||
let _ = session.text(format!(r#"{{"code":500,"message":"{}"}}"#, e)).await;
|
||||
break;
|
||||
}
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
|
||||
let _ = session.close(None).await;
|
||||
|
||||
Ok(resp)
|
||||
}
|
||||
```
|
||||
|
||||
## 客户端示例
|
||||
|
||||
### TypeScript 客户端
|
||||
|
||||
```typescript
|
||||
import { ReconnectingWebSocket } from '@kevisual/router';
|
||||
|
||||
const ws = new ReconnectingWebSocket('ws://localhost:4002/api/router', {
|
||||
onOpen: () => {
|
||||
console.log('connected');
|
||||
},
|
||||
onMessage: (data) => {
|
||||
console.log('received:', data);
|
||||
}
|
||||
});
|
||||
|
||||
// 调用路由
|
||||
ws.send({
|
||||
type: 'router',
|
||||
path: 'demo',
|
||||
key: '01',
|
||||
payload: { name: 'test' }
|
||||
});
|
||||
```
|
||||
|
||||
### 原生 WebSocket
|
||||
|
||||
```javascript
|
||||
const ws = new WebSocket('ws://localhost:4002/api/router?token=xxx&id=client1');
|
||||
|
||||
ws.onopen = () => {
|
||||
// 调用路由
|
||||
ws.send(JSON.stringify({
|
||||
type: 'router',
|
||||
path: 'demo',
|
||||
key: '01',
|
||||
payload: { name: 'test' }
|
||||
}));
|
||||
};
|
||||
|
||||
ws.onmessage = (event) => {
|
||||
const data = JSON.parse(event.data);
|
||||
console.log('received:', data);
|
||||
};
|
||||
|
||||
// 发送 ping
|
||||
ws.send('ping');
|
||||
|
||||
// 关闭连接
|
||||
ws.send('close');
|
||||
```
|
||||
|
||||
## 连接示例
|
||||
|
||||
```bash
|
||||
# 基础连接
|
||||
wscat -c ws://localhost:4002/api/router
|
||||
|
||||
# 带 token 和 id
|
||||
wscat -c "ws://localhost:4002/api/router?token=xxx&id=client1"
|
||||
|
||||
# 发送路由请求
|
||||
{"type":"router","path":"demo","key":"01"}
|
||||
```
|
||||
Reference in New Issue
Block a user