微信小程序路由实战

欢迎来到我博客阅读：BlueSun - 微信小程序路由实战

0. 目录

• 1. 前言
• 2. 智能路由跳转 — Navigator 模块
• 3. 虚拟路由策略 — Router 模块

• 4. 落地中转策略 — LandTransfer 模块

  • 4.1. 对于要解决的第一个问题：统一的落地页
  • 4.2. 对于第二个要解决的问题：短链参数
  • 4.3. LandTransfer 模块设计

• 5. 更好的开发体验

  • 5.1. Typescript + Router
  • 5.2. 智能生成路由配置
  • 5.3. 自定义组件跳转
• 6. 整体架构图
• 7. 最后的最后

1. 前言

在微信小程序由一个 App()实例，和众多Page()组成。而在小程序中所有页面的路由全部由框架进行管理，框架以栈的形式维护了所有页面，然后提供了以下 API 来进行路由之间的跳转：

1. wx.navigateTo
2. wx.redirectTo
3. wx.navigateBack
4. wx.switchTab
5. wx.reLaunch

但是，对于一个企业应用，把这些问题留给了开发者：

1. 原生 API 使用了 Callback 的函数实现形式，与我们现代普遍的 Promise 和 async/await 存在 gap。
2. 基于小程序路由的设计，暴露给外部的是真实路由（如扫码，公众号链接等方式），对后续项目重构留下历史包袱。
3. 小程序页面栈最多十层， 在超过十层后 wx.navigateTo 失效，需要开发者判断使用 wx.redirectTo 或其他API
4. 小程序页面栈存在一种特殊的页面：Tab 页面，需要使用 wx.switchTab 才能跳转。需要开发者主动判断，不方便后期改动 Tab 页面属性。
5. 额外的，对于小程序码，要使用无数量限制 API wxacode.getUnlimited ，存在参数长度限制32位以内。需要开发者自行解决。

而本文，期望能对这若干问题，逐个提供解决方案。

2. 智能路由跳转 — Navigator 模块

在这里我们一起解决：

1. 原生 API 非 Promsie
2. 页面栈突破十层时特殊处理
3. 特殊页面 Tab 的跳转处理

我们的思路是，希望能设计一种逻辑，根据场景来自动判断使用哪个微信路由 API，然后对外只提供一个函数，例如：

gotoPage('/pages/goods/index')

具体逻辑如下：

1. 当跳转的路由为小程序 tab 页面时，则使用 wx.switchTab。
2. 当页面栈达到 10 层之后，如果要跳转的页面在页面栈中，使用 wx.navigateBack({ delta: X }) 出栈到目标页面。
3. 当页面栈达到 10 层之后，目标页面不存在页面栈中，使用 wx.redirectTo 替换栈顶页面。
4. 其他情况使用 wx.navigateTo

顺带的，我们把这个函数以 Promise 形式实现，以及支持参数作为 object传入，例如：

gotoPage('/pages/goods/index', { name: 'jc' }).then(...).catch(...);

大部分场景下，只要使用gotoPage就能满足。

那肯定也会有特定的情况，需要显式的指定使用 navigateTo/switchTab/redirectTo/navigateBack的哪一个。

那么我们也按照类似的实现，满足相同模式的 API

navigateTo('/pages/goods/index', { name: 'jc' }).then(...).catch(...);
switchTab('/pages/goods/index', { name: 'jc' }).then(...).catch(...);
redirectTo('/pages/goods/index', { name: 'jc' }).then(...).catch(...);
navigateBack('/pages/goods/index', { name: 'jc' }).then(...).catch(...);

这些函数都可以内聚到同一个模块，我们称其为：Navigator

const navigator = new Navigator();
navigator.gotoPage(...);
navigator.navigateTo(...);
navigator.switchTab(...);
navigator.redirectTo(...);
navigator.navigateBack(...);

模块设计：

3. 虚拟路由策略 — Router 模块

在这里，我们解决：

1. 对外暴露了真实路由，导致历史包袱沉重的问题。

在许多应用开发中，我们经常需要把某种模式匹配到的所有路由，全都映射到同个页面中去。
例如，我们有一个 Goods 页面，对于所有 ID 各不相同的商品，都要使用这个页面来承载。

那么在代码层面上，期望能实现这样的调用方式：

// 创建路由实例
const router = new Router();

// 注册路由
router.register({
  path: '/goods/:id', // 虚拟路由
  route: '/pages/goods/index', // 真实路由
});

// 跳转到 /pages/goods/index，参数: onLoad(options) 的 options = { id: '123' }
router.gotoPage('/goods/123');

// 跳转到 /pages/goods/index，参数: onLoad(options) 的 options = { id: '456' }
router.gotoPage('/goods/456');

Class Router 的核心逻辑是完成：

1. 路由的注册，完成「虚拟路径」和「真实路径」关系的存储。
2. 满足「虚拟路径」到「真实路径」的转换，并且识别「动态路径参数」（dynamic segment）。
3. 路由跳转。

对于「路由的注册」，我们在其内部存储一个 map 就能完成。

而对于「路径的转换」， vue-router 有类似的实现，通过其源码发现，内部是使用 path-to-regexp 作为路径匹配引擎，我们可以拿来用之。

然后对于「路由的跳转」，我们可以直接复用上面提到的 Navigator 模块，通过输入真实路径，来完成路由的跳转。

模块设计：

其中：

1. RouteMatcher：提供动态路由参数匹配功能，内部使用 path-to-regexp 作为路径匹配引擎。
2. Route: 为每个路径创建路由器，存储每个路由的虚拟路径和真实路由的关系。
3. Router：整合内部各模块，对外提供统一且优雅的调用方式。

4. 落地中转策略 — LandTransfer 模块

在这里，我们解决：

1. 小程序扫码、公众号链接等场景下的落地页统一。
2. 小程序码，对于无限量API wxacode.getUnlimited ，突破参数32位长度限制。

4.1. 对于要解决的第一个问题：统一的落地页

我们把如：扫小程序码、公众号菜单、公众号文章等方式打开小程序某个页面的路径称为「外部路由」。

根据小程序的设计，暴露给外部的连接是真实的页面路径，如：/pages/home/index，该设计在实践中存在的弊端：各个落地页分散，后期修改真实文件路径难度大。

在 「中长生命周期」 产品中，随着产品的迭代，我们难免会遇到项目的重构。如果分发出去的都是没经过处理的真实路径的话，我们重构时就会束手束脚，要做很多的兼容操作。因为你不知道，分发出去的小程序二维码， 有多少被打印到实体物料中。

那么，「虚拟路由」+「落地中转」 的策略就显得基本且重要了。

「虚拟路由」的功能，Router 模块给我们提供了支持了，我们还需要对外提供一个统一的落地页面，让它来完成对内部路由的中转。

基本逻辑：

1. 分发出去的真实路由，指向到唯一的落地页面，如：$LAND_PAGE: /pages/land-page/index
2. 由这个落地页面，进行内部路由的重定向转发，通过接收 参数，如：path=/user&name=jc&age=18

在代码层面上，我们希望能实现这样的使用：

// /pages/land-page/index.ts

const landTransfer = new LandTransfer(landTransferOptions);

Page({
  onLoad(options) {
      landTransfer
        .run(options)
        .then(() => {...})
        .catch(() => {...});
  }
});

然后针对 TS，我们还可以使用装饰器版本，更加简便：

import { landTransferDecorator } from 'wxapp-router';

Page({
  @landTransferDecorator(landTransferOptions)
  onLoad(options) {
    // ...
  },
});

4.2. 对于第二个要解决的问题：短链参数

微信小程序主要提供了两个接口去生成小程序码：

1. wxacode.get: 获取小程序码，适用于需要的码数量较少的业务场景。通过该接口生成的小程序码，永久有效，数量限制为 100,000 个
2. wxacode.getUnlimited: 获取小程序码，适用于需要的码数量极多的业务场景。通过该接口生成的小程序码，永久有效，数量暂无限制。

第一种方式，wxacode.get 数量限制为 10w 个，虽然量很大了，绝大多数的小程序可能用不到这个量。

但如果我们运营的是一个中大型电商小程序的话，假如：1w 种商品 x 10 种商品规格，那就会超过这个数量。到时候再进行改造，就困难了。

所以，如果抱着是运营一个 「中长生命周期」 的产品的话，我们会使用第二种方式：wxacode.getUnlimited

不尽人意的是，虽然它没有数量限制，但是对参数会有 32 个字符的限制，显然是不够用的（一个 uuid 就 32 字符了）。

对于这种情况，我们可以使用「短链参数」的形式解决，由于wxacode.getUnlimited 会通过 scene字段作为 query 参数传递给小程序的，那么我们可以通过 scene参数来实现短链服务，这需要后端配合。

前后端交互如下：

1. 当小程序需要生成小程序码的时候，请求后端提供的接口，例如：/api/encodeShortParams
2. 后端把内容转换为 32 字符内的字符串，存储到数据库中。
3. 后端通过 wxacode.getUnlimited 接口，以短链字符串作为 scene的值，以商定好的统一落地页 $LAND_PAGE作为 page值，生成小程序码。
4. 当通过小程序码进入小程序，小程序获取到 scene参数，请求后端提供的接口，例如：/api/decodeShrotParams
5. 小程序理解内容，跳转到目标页面中去。

而前端对于统一落地页的逻辑处理，我们只需要在第一个问题的基础上，增加一个转换短链参数内容的逻辑就行了：

代码层面上，我们我们只需要多定义转换短链参数的方式：convertScenePrams

// in /pages/land-page/index.js
import { landTransferDecorator } from 'wxapp-router';

const landTransferOptions = {
  // 此处接收 onLoad(options) 中的 options.scene
  convertSceneParams: (sceneParams) => {
    return API.convertScene({ sceneParams }).then((content) => {
      // 假如后端存的是 JSON 字符串，前端decode
      // 要求 content = { path: '/home', a: 1, b:2 }
      return JSON.parse(content);
    });
  },
};

Page({
  @landTransferDecorator(landTransferOptions)
  onLoad(options) {
    // ...
  },
});

而其中的 API.convertScene 就对接服务端提供 HTTP 接口服务来完成。

4.3. LandTransfer 模块设计

5. 更好的开发体验

5.1. Typescript + Router

对于小程序内部的路由跳转，我们除了指定一个字符串的路由，我们是否也可以通过链式调用，像调用函数那样去跳转页面呢？类似这样；

routes.pages.user.go({ name: 'jc' });

这样做的好处是：

1. 更自然的调用方式。
2. 能结合 TS，来做到类型提示和联想。

由于事先 wxapp-router 并不知道开发者需要注册的路由是什么样的，所以路由的 TS 声明文件，需要开发者来定义。

例如，我们在项目中维护一份路由文件：

// config/routes.ts

// 创建路由实例
const router = new Router();

const routesConfig = [{
  path: '/user',
  route: '/pages/user/index',
}, {
  path: '/goods',
  route: '/pages/goods/index',
}]；

type RoutesType {
  paegs: {
    user: Route<{name: string}>,
    goods: Route,
  }
}

// 注册路由
router.batchRegister(routesConfig);

// 获取 routes
const routes: RoutesType = router.getRoutes();

export default routes;

然后在别的地方使用它：

import routes from './routes.ts';

routes.pages.user.go({ name: 'jc' });

5.2. 智能生成路由配置

如果路由变多的时候，我们还需要对每个路由手动去编写 RoutesType 的话，就有点难受了。

在小程序中，我们把正式路由都配置到 app.json ，那么在遵循既定的项目结构情况下，我们可以通过自动构建，完成大部分工作，例如：

1. 智能注册路由
2. 智能识别页面入参声明

5.3. 自定义组件跳转

以上都是脚本层面的使用，小程序中还有 wxml, 我们希望能在有个组件快速使用：

<Router path="/pageA" query="{{pageAQuery}}"></Router>
<Router path="/pageB" query="{{pageBQuery}}" type="redirectTo"></Router>
<Router path="/pageC/katy"></Router>

那么，实现一个自定义组件，然后把 Router模块包装一下，问题就不大了。

示例代码：

// components/router.wxml

<view class="wxapp-router" bind:tap="gotoPage">
    <slot />
</view>

// components/router.ts

Component({
    properties: {
        path: String,
        type: {
            type: String,
            value: 'gotoPage'
        },
        route: String,
        query: Object,
        delta: Number,
        setData: Object,
    },

    methods: {
        gotoPage(event) {
            const router = getApp().router;
            const { path, route, type, query} = this.data;
            const toPath = route || path;

            if (['gotoPage', 'navigateTo', 'switchTab', 'redirectTo'].includes(type)) {
                (router as any)[type](toPath, query);
            }

            if (type === 'navigateBack') {
                const { delta, setData } = this.data;
                router.navigateBack({ delta }, { setData })
            }
        }
    }
})

6. 整体架构图

最后，我们来整体回顾一下各模块的设计

1. Navigator：封装微信原生路由 API，提供智能跳转策略。
2. LandTransfer：提供落地页中转策略。
3. RouteMatcher：提供动态路由参数匹配功能。
4. Route: 为每个路径创建路由器。
5. Router：整合内部各模块，对外提供优雅的调用方式。
6. Logger：内部日志器。
7. Path-to-regexp: 开源社区的路由匹配引擎。

7. 最后的最后

鉴于写过很多的实战类的文章，会有不少同学想要到整体的示例代码，这次我就索性写了一个工具，Enjoy it!

wxapp-router： 🛵 The router for Wechat Miniprogram