用途
该技能面向需要把 Dart Web 服务器从 Shelf 迁移到 Relic 的开发者。Relic 用单个包替代 shelf、shelf_router 和 shelf_web_socket,核心概念(处理器、中间件、请求、响应)基本延续,并提升了类型安全性。技能以并排对照的形式列出每一项 API 变更,便于逐项替换。
主要能力
技能覆盖以下迁移要点:
- 依赖:移除 Shelf 相关包,改为添加 relic。
- 服务器启动:从 shelf_io.serve 改为 RelicApp().serve。
- 处理器:Shelf 处理器直接返回 Response;Relic 处理器返回 Result(通常是 Response),且响应体需要显式的 Body 对象。
- 路由:Shelf 路径参数使用 <id> 并作为处理器参数传入;Relic 使用 :id 并从 request.pathParameters 读取。
- 响应与 Body:Shelf 接受纯字符串并通过 headers 设置 Content-Type;Relic 要求 Body 对象,Content-Length 自动设置,MIME 类型可自动检测或显式指定。
- 请求头:Shelf 基于字符串、需手动解析;Relic 提供类型安全的访问器并自动解析。
- 中间件:Shelf 的 Pipeline 对所有请求(包括 404)应用中间件;Relic 的 router.use() 按路径限定中间件作用范围,且只在匹配的路由上运行,未匹配请求(404)绕过中间件直接进入 fallback 处理器。
- 上下文:Shelf 使用动态 map 并手动类型转换;Relic 使用类型安全的 ContextProperty 与扩展方法。
- WebSocket:Shelf 需要单独的 shelf_web_socket 包;Relic 内置,可从任意处理器返回 WebSocketUpgrade。
使用方式
技能以并排代码对照的形式呈现每一项变更,并给出完整的 Shelf 与 Relic 对照示例,以及一张速查表,列出常见写法的对应关系,例如:
- import 'package:shelf/shelf.dart' 对应 import 'package:relic/relic.dart'
- shelf_io.serve(handler, host, port) 对应 RelicApp().serve(address: addr, port: port)
- Response.ok('text') 对应 Response.ok(body: Body.fromString('text'))
- Router()..get('/path/<id>', (req, id) {...}) 对应 RelicApp()..get('/path/:id', (req) {...})
- request.headers['name'] 对应 request.headers.name(类型化)
- Pipeline().addMiddleware(mw).addHandler(h) 对应 app.use('/', mw)
- request.change(context: {...}) 对应 ContextProperty<T>()[req] = value
- shelf_web_socket 包对应内置 WebSocketUpgrade
适用场景
适用于把现有 Shelf 代码转换为 Relic、替换 Shelf 相关依赖,或了解两者 API 对应关系的场景。
限制
资料未提供 Relic 的具体版本号、性能数据、兼容性范围或迁移后的验证方式,这些内容暂未提供。