路由系统详解

简介

cHttpServerRouter 是 HttpServer 的核心组件，负责将 HTTP 请求映射到对应的处理程序。支持手动路由和自动路由两种模式，以及 HTTP 方法限定、路由组等高级特性。

路由执行流程

┌─────────────────────────────────────────────────────────────┐
│                      请求到达                                │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  1. 静态文件检查                                             │
│     └─> 如果匹配 WebRoot 中的文件，直接返回静态文件            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  2. 执行前置中间件 (RouteBefore)                              │
│     └─> 可以拦截请求、验证权限、记录日志等                    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  3. 路由匹配                                                 │
│     ├─> a) 检查手动注册的路由                                 │
│     ├─> b) 检查自动路由 (如果开启)                            │
│     └─> c) 404 未找到                                        │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  4. 执行控制器方法                                           │
│     └─> 调用匹配的 Controller@Action                          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  5. 执行后置处理 (RouteAfter)                                 │
│     └─> 可以添加响应头、记录响应日志等                        │
└─────────────────────────────────────────────────────────────┘

手动路由

基础路由

' 注册控制器
Call Server.Router.Reg("User", New cUserController)
Call Server.Router.Reg("Api", New cApiController)

' 添加路由
Call Server.Router.Add("/", "User@Index")           ' GET/POST 均可访问
Call Server.Router.Add("/list", "User@List", OnlyGet)  ' 仅 GET
Call Server.Router.Add("/create", "User@Create", OnlyPost)  ' 仅 POST

HTTP 方法限定

' 任意方法（默认）
Call Server.Router.Add("/any", "Home@Any", Any_)

' 仅 GET
Call Server.Router.Add("/get", "Home@Get", OnlyGet)

' 仅 POST
Call Server.Router.Add("/post", "Home@Post", OnlyPost)

' 仅 PUT
Call Server.Router.Add("/put", "Home@Put", OnlyPut)

' 仅 DELETE
Call Server.Router.Add("/delete", "Home@Delete", OnlyDelete)

RESTful API 路由示例

' 用户资源 RESTful API
Call Server.Router.Reg("User", New cUserController)

' GET    /users       -> 列表
Call Server.Router.Add("/users", "User@Index", OnlyGet)

' GET    /users/:id   -> 详情
Call Server.Router.Add("/users/detail", "User@Detail", OnlyGet)

' POST   /users       -> 创建
Call Server.Router.Add("/users", "User@Create", OnlyPost)

' PUT    /users/:id   -> 更新
Call Server.Router.Add("/users/update", "User@Update", OnlyPut)

' DELETE /users/:id   -> 删除
Call Server.Router.Add("/users/delete", "User@Delete", OnlyDelete)

控制器编写规范

' cUserController.cls
Option Explicit

' GET /users
Public Sub Index(ctx As cHttpServerContext)
    Dim users As New Scripting.Dictionary
    users("items") = Array("张三", "李四")
    users("total") = 2
    ctx.Response.Json users, 0, "Success"
End Sub

' GET /users/detail?id=123
Public Sub Detail(ctx As cHttpServerContext)
    Dim id As String
    id = ctx.Request.QueryString("id")
    
    Dim user As New Scripting.Dictionary
    user("id") = id
    user("name") = "张三"
    ctx.Response.Json user
End Sub

' POST /users
Public Sub Create(ctx As cHttpServerContext)
    ' 获取表单数据
    Dim name As String, email As String
    name = ctx.Request.Form("name")
    email = ctx.Request.Form("email")
    
    ' 或获取 JSON 数据
    ' name = ctx.Request.Json.GetItem("name")
    
    ' 业务逻辑...
    
    ctx.Response.Json Nothing, 0, "创建成功"
End Sub

' PUT /users/update
Public Sub Update(ctx As cHttpServerContext)
    Dim id As String
    id = ctx.Request("id")  ' 自动从 Query/Form/Json 获取
    
    ctx.Response.Json Nothing, 0, "更新成功"
End Sub

' DELETE /users/delete
Public Sub Delete(ctx As cHttpServerContext)
    Dim id As String
    id = ctx.Request.QueryString("id")
    
    ctx.Response.Json Nothing, 0, "删除成功"
End Sub

自动路由

开启自动路由后，框架会根据 URL 路径自动解析控制器和方法。

' 开启自动路由
Server.Router.AutoRoute = True

URL 解析规则

格式: /ControllerName/ActionName?param1=value1&param2=value2

示例:
  /User/List         -> User 控制器的 List 方法
  /User/Detail?id=1  -> User 控制器的 Detail 方法
  /Home/Index        -> Home 控制器的 Index 方法

自动路由使用示例

' 只需要注册控制器，不需要手动添加路由
Call Server.Router.Reg("User", New cUserController)
Call Server.Router.Reg("Product", New cProductController)

' 开启自动路由
Server.Router.AutoRoute = True

' 以下 URL 会自动路由：
' GET  /User/List    -> 调用 cUserController.List
' GET  /User/Detail  -> 调用 cUserController.Detail
' POST /Product/Add  -> 调用 cProductController.Add

手动路由 vs 自动路由

特性	手动路由	自动路由
性能	更快（直接字典查找）	稍慢（需要解析 URL）
灵活性	可自定义 URL 路径	遵循固定格式
安全性	只暴露注册的路由	暴露所有公共方法
适用场景	API 服务、生产环境	快速开发、后台管理

路由与中间件配合

' 前置中间件：登录验证
Public Sub AuthMiddleware(ctx As cHttpServerContext)
    ' 排除登录接口
    If ctx.Request.PathInfo = "/login" Then Exit Sub
    
    ' 检查 Session
    If ctx.Session("user_id") = "" Then
        ctx.Response.State401 "请先登录"
        ctx.fIsAbort = True  ' 终止后续处理
    End If
End Sub

' 注册中间件
Call Server.RouteBefore.Add("auth", New cAuthMiddleware)

' 路由注册（会被 auth 拦截检查）
Call Server.Router.Add("/api/data", "Api@Data", OnlyGet)

路由性能优化建议

1. 生产环境使用手动路由：性能更好，安全性更高
2. 静态文件优先：WebRoot 中的文件会优先返回，不进入路由
3. 合理使用 HTTP 方法限定：可以更快匹配合适的路由字典
4. 控制器缓存：控制器对象只注册一次，重复使用

---

最后更新: 2026-05-17