跳到主要内容
版本：4.0-rc

WebAPI 路由系统

一、路由概述​

TouchSocket.WebApi 提供了强大且灵活的路由系统，支持多种路由配置方式，包括默认路由、自定义路由模板和正则表达式路由。路由系统能够精确匹配请求 URL 到对应的 API 方法，并提供友好的错误处理机制。

路由匹配机制

点击观看视频教程

课程

二、默认路由​

2.1 路由格式​

当没有显式指定路由时，系统会自动使用默认路由规则：

默认路由格式：/{服务类名}/{方法名}

特点：

  • 不区分大小写
  • 服务类名使用完整类名（包括 "Server" 后缀）
  • 方法名即为实际方法名称

2.2 示例​

🔄 正在加载代码...

访问路径：

  • /DemoApiServer/Sum?a=10&b=20
  • /demoapiserver/sum?a=10&b=20 （大小写不敏感）

三、自定义路由​

3.1 使用 Router 特性​

使用 [Router] 特性可以自定义路由规则，支持占位符替换：

占位符说明：

  • [api] - 服务类名（使用完整类名）
  • [action] - 方法名

3.2 多路由配置​

一个方法可以配置多个路由路径：

🔄 正在加载代码...

访问路径：

  • /ApiServer/Sumab?a=10&b=20
  • /ApiServer/Sum?a=10&b=20

3.3 自定义路由路径​

可以完全自定义路由路径，不使用占位符：

🔄 正在加载代码...

访问路径：

  • /api/custom/calculate?x=5&y=3

3.4 类级别路由​

[Router] 特性可以应用于类级别，为类中的所有方法设置统一的路由前缀：

[Router("/api/v1/[api]")]
public class UserApiServer : SingletonRpcServer
{
    [Router("[action]")]
    [WebApi(Method = HttpMethodType.Get)]
    public string GetUser(int id)
    {
        return $"User: {id}";
    }
}

访问路径：/api/v1/UserApiServer/GetUser?id=1

说明：

  • 方法级别的 [Router] 会覆盖类级别的设置
  • 如果方法没有设置 [Router]，则会继承类级别的路由模板

四、正则表达式路由​

4.1 RegexRouter 特性​

使用 [RegexRouter] 特性可以定义基于正则表达式的路由规则，适用于需要动态路径参数的场景。

🔄 正在加载代码...

说明：

  • 正则表达式不区分大小写
  • 支持复杂的路由模式匹配
  • 可以通过 IWebApiCallContext 获取实际请求的 URL 进行解析

4.2 正则路由示例​

常见正则路由模式：

// 匹配数字 ID
[RegexRouter(@"^/users/\d+$")]        // /users/123

// 匹配 GUID
[RegexRouter(@"^/orders/[0-9a-f-]+$")] // /orders/123e4567-e89b

// 匹配多段路径
[RegexRouter(@"^/api/v\d+/products/\d+$")] // /api/v1/products/100
注意

正则路由标记的方法，如果没有其他的常规路由的话，在Swagger中将不会被列出。

五、路由匹配规则​

5.1 匹配优先级​

路由系统按照以下优先级进行匹配：

  1. 精确匹配（字典查询，O(1) 性能）
  2. 正则表达式匹配（按注册顺序依次尝试）

5.2 匹配流程​

  1. 首先尝试精确路由匹配（包括默认路由和 Router 特性定义的路由）
  2. 如果精确匹配失败，则尝试正则表达式路由匹配
  3. 如果路由匹配成功但 HTTP 方法不匹配，返回 405 Method Not Allowed
  4. 如果没有找到任何匹配的路由，返回 404 Not Found

5.3 路由规范化​

  • 自动补齐斜杠：路由模板如果没有以 / 开始，系统会自动补齐
  • 大小写不敏感：所有路由匹配均不区分大小写
  • URL 规范化：请求 URL 会被转换为小写进行匹配

六、路由配置最佳实践​

6.1 命名建议​

  • 使用清晰、语义化的路由路径
  • 遵循 RESTful 风格（推荐但非强制）
  • 避免过于复杂的路由规则

6.2 占位符使用​

  • [api] 占位符适用于需要包含服务类名的场景
  • [action] 占位符适用于需要包含方法名的场景
  • 如果不需要服务类名或方法名，可以使用完全自定义的路由

6.3 正则路由使用​

  • 仅在需要动态路径参数时使用正则路由
  • 正则表达式应尽量简洁明了
  • 考虑性能影响，正则匹配比精确匹配慢

6.4 多路由配置​

  • 可以为向后兼容或别名提供多个路由
  • 避免过多的路由别名，保持 API 的简洁性

七、常见问题​

7.1 路由冲突​

问题：多个方法配置了相同的路由路径和 HTTP 方法。

解决方案：

  • 确保每个路由路径和 HTTP 方法的组合是唯一的
  • 使用不同的 HTTP 方法（GET、POST、PUT、DELETE 等）
  • 使用不同的路由路径

7.2 占位符不生效​

问题：使用了 [api] 或 [action] 占位符，但路由没有按预期生成。

解决方案：

  • 检查占位符是否被正确包含在方括号中：[api] 而不是 {api}
  • 确认路由模板以 / 开始
  • 验证服务类名和方法名是否符合预期

7.3 正则路由不匹配​

问题：正则表达式路由无法匹配预期的 URL。

解决方案：

  • 检查正则表达式语法是否正确
  • 记住正则路由是不区分大小写的
  • 使用在线正则测试工具验证表达式
  • 确保正则表达式以 ^ 开始，以 $ 结束（完整匹配）

八、总结​

TouchSocket.WebApi 的路由系统提供了：

  • 灵活性：支持默认路由、自定义路由和正则路由
  • 高性能：精确匹配使用字典查询，性能优异
  • 易用性：简洁的特性配置，占位符支持
  • 可扩展性：支持类级别和方法级别的路由配置

通过合理使用路由系统，可以构建清晰、易维护的 Web API 接口。

编辑此页
最后由 若汝棋茗 于 更新