Midway 5 Release: Design, Stability, and Plugin Architecture Explained

For years I have been busy upgrading Midway, the Node.js web application solution from Taobao that aims to simplify front‑back separation for developers. Midway 5 has now been officially released after months of development, bringing a host of reflections and improvements.

Code Style Choice

With the emergence of ES6/ES2015, using generators and promises together has become stable and standardized, and the upcoming async/await further simplifies asynchronous code. Before Koa 2.0, Koa 1.0 offers a balanced choice; using yield flattens most async operations and remains compatible with future Koa 2.0 code.

Some wonder why Babel is not used. Since Node.js does not natively support these syntax features and even --harmony cannot enable them, we avoid Babel to maintain enterprise‑grade stability for millions of users.

Stability

Framework stability differs from business stability: business code needs fault tolerance, while the framework must provide a safety net. Simple try/catch or promise.catch may suffice for business code, but the framework must handle more complex failure scenarios.

Midway employs a Master/Agent/Worker process model, launching N+2 processes. Workers communicate with Master/Agent, so any process error or crash creates a complex situation that must be fully handled.

Standard process handling includes graceful shutdown upon receiving normal messages and forcibly terminating lingering child processes.

Unexpected exceptions must be logged before safe exit or custom actions.

When non‑master processes fail, special handling is required. For example, the Agent process is critical; if it fails on first launch, a forced exit is needed, and a self‑restart mechanism must guard against accidental crashes and memory leaks.

Worker processes, started via the cluster mechanism, share many handling steps with the Agent, but also need to consider process count (defaulting to CPU cores, possibly reduced for memory safety) and limit restart frequencies with alerts.

Framework Design

Midway’s new philosophy is “Everything is a plugin,” meaning the framework and applications are both composed of plugins, maximizing code reuse and simplifying usage.

A simple application’s structure mirrors that of a plugin and the framework itself, forming a unified convention after extensive discussion within the Node team.

Beyond the usual node_modules, Taobao adds a bin/app directory and xtpl templates; the _bin folder is the launch entry point.

All plugins share the same directory layout as applications, except they lack controllers and routers. The key lies in the loading mechanism.

Midway’s loading logic is straightforward:

Load plugins in order.

Load the application as the final plugin.

Later plugins override earlier ones.

The framework must load configuration files, Koa extensions, middleware, controllers, and routes via a generic loader, which roughly looks like the diagram below.

The core of this method is a tryRequire operation that loads, validates, merges, and returns modules, covering most use cases.

Details and Trade‑offs

Developing an enterprise‑grade framework is never simple; the main architecture is relatively easy, but the details differentiate frameworks.

Compatibility

Historical baggage often appears in major version upgrades, making backward compatibility a headache. Midway’s earlier versions used a Proxy approach exposing APIs via midway.getXXXX. The new process loading shifts Midway from a Worker to a Master process, breaking the old pattern.

After extensive discussion, the entry file (the require part) was moved to the Worker, while the user‑facing server.js became midway/server, providing a satisfactory compromise.

Testing and Debugging

Embedding the Worker mechanism into Midway means the traditional app.js debugging no longer works; developers must now debug via bin/server.js, which is more cumbersome.

Leveraging the new IPC communication, we can debug by launching a single process, allowing test cases to run without spawning multiple processes.

In most cases, mocha + supertest suffices, though occasional issues arise when multiple Agent processes cannot reliably determine instance identity in the same directory.

Upgrade Mechanism

Midway’s new design simplifies development; forcing users to upgrade is unrealistic, so we embed plugins as internal dependencies and let the framework manage versions, consolidating build and start scripts. This has noticeably reduced support tickets.

Framework upgrades are controlled by npm tag versions handled by the scaffolding tool; each deployment installs the latest tagged release.

Configuration example:

{
  "publishConfig": {
    "tag": "release-5.1"
  }
}

While this approach can introduce risks—e.g., a plugin upgrade breaking the framework—we enforce semver compliance and maintain sufficient test coverage. Incompatible changes trigger a coordinated tag bump for the entire framework, minimizing user impact.

Conclusion

Behind every solution and framework lies a team of developers debating minutiae, responsible both to users and themselves. Midway will not last a century, but we aim to do a little more for the things we can.

With Midway 5 released, we can focus more on serving users and improving efficiency rather than constant trade‑offs.

Remember to stay true to the original intent and keep moving forward.

(Unless otherwise stated, this article is licensed under CC BY‑NC‑ND 4.0)