Skip to main content

Release 4.0.0

· 6 minute read
Harry Chen
Harry Chen
Maintainer of Midway

今天，我们正式发布 Midway 4.0。

这是一次跨度很大的版本升级。它不是一次“把版本号从 3 改成 4”的常规发布，而是一次面向未来几年 Node.js 服务研发方式的重新整理：更清晰的启动机制、更统一的函数式能力、更明确的组件边界，以及更适合现代全栈协作的开发体验。

从 3.x 走到 4.0，我们做了很多克制但关键的调整。很多历史能力被重新审视，保留下来的是长期稳定、可维护、可组合的部分；新增的能力，也尽量围绕一个目标展开：让 Midway 在大型应用、组件体系、函数式接口、一体化开发这些场景下更顺手，也更可预期。

为什么是 4.0​

Midway 过去这些年一直在同时面对几类需求：

  • 传统 Node.js 服务端应用要稳定
  • 组件体系要可复用、可扩展
  • 函数式写法要真正可落地，而不只是“能写”
  • 一体化开发要从概念走向工程化
  • 框架内部机制要更透明，减少黑盒行为

在 3.x 时代，这些能力已经逐步成型；到了 4.0，我们决定把很多“约定优先但不够显式”的能力重新收束，换成更清楚、更稳定的框架边界。

所以 4.0 的关键词不是“更多功能”，而是：

  • 更显式
  • 更统一
  • 更现代
  • 更适合长期维护

4.0 的几个核心变化​

1. Node.js 基线升级到 20+​

Midway 4.0 从 Node.js 20 开始支持。

这意味着我们可以更放心地使用现代运行时能力，也意味着框架内部许多基础设施终于可以建立在一个更稳定的底座之上。对用户来说，这会减少很多历史兼容负担；对框架来说，这让后续演进空间明显变大。

2. 启动机制从“隐式扫描”转向“显式声明”​

这是 4.0 最重要的变化之一。

过去，框架会在启动时做很多目录扫描、自动绑定、隐式发现。它在小项目里看起来很方便，但在大型工程、复杂组件、调试排查、测试隔离这些场景里，黑盒成本会越来越高。

4.0 改成了更显式的方式：

  • 需要扫描什么，由用户或组件明确声明
  • 组件自己的加载边界更清楚
  • 启动行为更可预测
  • 测试和调试更容易定位问题

这个变化会让刚上手时多写一点配置，但长期看，它会让项目结构、工程边界和认知成本都更健康。

3. 函数式能力正式走向统一​

4.0 不再把函数式能力当成一条旁支路线，而是把它整理成了清晰的一套主干能力。

现在统一推荐通过 @midwayjs/core/functional 使用函数式 API，比如：

  • defineConfiguration
  • defineApi
  • useContext
  • useInject
  • useConfig
  • useLogger

这意味着：

  • 函数式接口的入口统一了
  • 组件提供 functional 能力的方式统一了
  • 前后端共享契约、一体化协作更顺了
  • 文档、教程、样例都可以围绕同一套模型展开

如果说过去函数式写法更像“一个实验方向”，那么在 4.0，它已经成为 Midway 的正式能力之一。

4. 验证能力升级为新的 validation 体系​

4.0 中我们新增了 @midwayjs/validation，用来替代原有的 validate 思路。

新的验证体系支持：

  • Joi
  • zod
  • class-validator

并且提供了更统一的扩展方式和更好的 i18n 支持。

这背后的考虑也很明确：验证器生态已经变化了，框架不应该继续把能力绑定在单一实现上。Midway 更适合做统一抽象层，把选择权和扩展能力交还给用户。

5. 组件边界更清楚，内部机制更稳定​

4.0 对核心容器、元数据管理、装饰器继承规则、生命周期、框架 hook、服务工厂等基础能力都做了系统整理。

这一部分不一定是最“显眼”的升级，但它对长期维护最关键。

包括但不限于：

  • 元数据管理机制重构
  • 装饰器继承规则更明确
  • 生命周期增加超时机制
  • 依赖注入和循环依赖提示更清晰
  • 默认开启 asyncLocalStorage
  • 一些历史遗留但语义不清的 API 被移除或重命名

这些改动共同指向一件事：让框架的内部行为和外部表现尽量一致，尽量减少“能跑但说不清为什么”的状态。

这一版也意味着一次取舍​

4.0 不是只做加法。

为了让整体模型更干净，我们也移除了或收缩了一部分历史能力，比如：

  • @midwayjs/decorator 独立包不再继续提供 4.x 版本
  • 一部分历史兼容 API 被清理
  • 部分低使用率、长期维护价值不高的组件退出 4.x 主线
  • 一些容易制造歧义的隐式能力被移除

这类调整一定会带来迁移成本，但我们更希望把 4.0 建立在一个能继续往前走很多年的基础上，而不是把旧负担不断往后拖。

对不同用户意味着什么​

如果你是 3.x 用户​

你会感受到两件事：

  • 一开始需要适应一些显式配置和新约定
  • 适应之后，项目边界会更清楚

迁移到 4.0 的重点，不只是把依赖版本改掉，而是理解新的启动方式、函数式导出路径、验证体系和部分核心 API 的变化。我们也会继续补充升级文档、教程和示例，帮助大家更平滑地完成迁移。

如果你是新用户​

4.0 会是一个更合适的起点。

你接触到的 Midway 将是一个更统一的版本：

  • 当前文档以 4.0 为主
  • 教程会同时覆盖 Class 和 Functional
  • 一体化能力会围绕真实工程方式展开
  • 新样例和新组件都优先按 4.0 设计

这会让学习路径更连贯，也更接近我们真正推荐的用法。

接下来我们会继续做什么​

4.0 正式发布，不代表演进结束；相反，它意味着很多事情终于可以在一个稳定基础上继续推进。

接下来我们会持续投入在这些方向：

  • 继续完善 4.0 文档与升级指南
  • 补齐 Class / Functional 双教程
  • 完善一体化开发、前端协作、Web Bridge 相关体验
  • 持续整理组件生态的 4.0 支持情况
  • 让 CLI、脚手架、官网和文档口径继续统一

感谢​

Midway 能走到 4.0，不是一两次重构，也不是一两个月冲刺的结果。

这是过去很多年里，框架、组件、文档、样例、社区反馈、线上实践一点点积累出来的版本。感谢所有提交过 issue、PR、示例、建议和反馈的朋友，也感谢所有在线上项目里真正使用 Midway、给我们带来真实问题的人。

框架真正的价值，从来不在发布日志里，而在一个个项目能不能更稳地上线、能不能更清楚地维护、能不能让团队协作少一些摩擦。

Midway 4.0，正式发布。

欢迎升级，欢迎继续给我们反馈。