serverpod-upgrading

Serverpod 次要/补丁版本升级

此 Serverpod 版本的要求：Dart 3.12.2+、Flutter 3.44.4+。请查看要安装版本的发行说明。

在所有软件包中使用相同的固定 Serverpod 版本。使用 CLI 进行升级。升级后，请让用户通过 serverpod start 启动服务器。切勿更新 CLI 工具；请停止并让用户自行更新。

1. 检查 Serverpod 的最新版本：https://pub.dev/packages/serverpod（除非用户指定了特定版本）。
2. 运行 serverpod version，确认工具版本正确。如果不正确，请停止并让用户安装正确的版本（最新版本使用 dart install serverpod_cli，指定版本使用 dart install serverpod_cli 3.x.x）。
3. 更新所有相关软件包中的 Serverpod 软件包版本：pubspec.yaml（server、client、flutter、shared）。
4. 在所有软件包中运行 dart pub upgrade。
5. 运行 serverpod generate。
6. 运行 serverpod create-migration。
7. 在项目根目录运行 dart analyze 并解决所有问题。
8. 确保 Dockerfile 使用至少 FROM dart:3.12.2 AS build。
9. 告知用户升级已完成，并让他们通过 serverpod start 启动服务器。

主要升级：Serverpod 3.x 至 4.0

完成常规升级流程后，处理以下破坏性变更。

流式传输： 已移除旧版流式会话和已弃用的流式 API。端点必须使用流式方法（Stream<T> 参数和返回类型）。请参阅 Serverpod Streams。

Future 调用： 已移除 pod.registerFutureCall(...)、FutureCall.invoke、pod.futureCallWithDelay(...) 和 pod.futureCallAtTime(...)。请在 FutureCall 类上定义方法，并通过生成的 pod.futureCalls API 安排这些方法。请参阅 Serverpod Scheduling。

服务器事件： postMessage 现在默认全局传递（禁用 Redis 时回退到本地传递）。如果消息不能离开服务器实例，请传入 scope: MessageScope.local。

ORM： 已移除已弃用的 orderDescending 参数。请使用 orderBy: (t) => t.column.desc() 或 orderByList。

端点： 已移除 ignoreEndpoint 注解。请使用 @doNotGenerate。

Web 服务器： 已移除已弃用的 Widget 类和旧版静态目录类。请使用 WebWidget、TemplateWidget、ListWidget、JsonWidget、RedirectWidget 和 StaticRoute.directory(...)。WidgetRoute.build 现在返回 Future<WebWidget?>，返回 null 时会响应 404。

身份验证： 已移除客户端参数 authenticationKeyManager；请使用 authSessionManager（Flutter）或 authKeyProvider。原生 Google Sign-In Web 实现已替换为 OAuth2，并已移除无效的电子邮件异常。flutter_secure_storage 版本必须为 10.0.0 或更高。在 Android 上，直接从 9.x 升级到 11.x 会导致用户退出登录；请先升级到 10.x。11.x 还需要 compileSdk 37。

服务器： SerializationManagerServer 已替换为 DatabaseSerializationManager。生成的项目现在会导入 src/generated/serverpod.dart 并使用 Serverpod(args) 创建服务器；Serverpod(args, Protocol(), Endpoints()) 形式仍可使用，但建议采用新的简化形式。

主要升级：Serverpod 2.x 至 3.0

完成常规升级流程后，请确保处理以下破坏性变更。

重大变更

Web 服务器（Relic）：

• handleCall：HttpRequest → Request，Future<bool> → FutureOr<Result，改为返回 Response.ok(...)，而不是写入响应
• request.remoteIpAddress → request.remoteInfo；request.headers.value('name') → request.headers['name']
• Widget 重命名：AbstractWidget→WebWidget，Widget→TemplateWidget，WidgetList→ListWidget，WidgetJson→JsonWidget，WidgetRedirect→RedirectWidget
• RouteStaticDirectory(...) → StaticRoute.directory(Directory(...))，并使用 cacheControlFactory

**Session.request：**Session 上新增可选的 request 属性（非 HTTP 会话中为 null）。

**枚举序列化：**现在默认使用 byName。在 YAML 中添加 serialized: byIndex 以保留旧行为。

模型：SerializableEntity → SerializableModel。YAML：parent=table → relation(parent=table)；database → scope=serverOnly；api → !persist。

身份验证：session.authenticated 现在是同步的。AuthenticationInfo.authId 不再可为空，userIdentifier 为 String。客户端：authenticationKeyManager → authKeyProvider。自定义处理程序接收的是已解包的 Bearer 令牌。

**已弃用：**旧版流式端点；请使用流式方法。