@acdlite/router 中文文档教程

Question

Router

JavaScript 应用程序功能路由的实验。

npm install --save @acdlite/router

该名称是有意通用的，因为它仍处于实验阶段（可能永远）。

主要特点：

• A router is defined using composable middleware functions.
• A router is a function that turns a path into a state object. That's it. This allows for total separation of history management from route matching.
• Because history management is separate, the server-side API is identical to the client-side API.

请参阅下面的模拟React Router API。

Should I use this?

不

，也许吧。 我目前在一个副项目中使用它，但我不会推荐它用于任何生产应用程序。

How it works

本项目上下文中的“路由器”是一个接受路径和回调的函数。 路由器通过一系列中间件将路径传递给状态对象。 中间件完成后，将使用最终状态对象调用回调（同步或异步），该对象可用于呈现应用程序。

历史管理被认为是一个单独的问题——只需向路由器传递一个字符串。 在客户端，使用像 history 这样的项目。 在服务器上，使用您最喜欢的 Web 框架，例如 Express 或 Koa.

const router = createRouter(...middlewares)

router('/some/path', (error, state) => {
  // Render app using state
})

Middleware

中间件是一个函数，它接受 Node 风格的回调（我们称它为监听器）并返回一个具有增强行为的新 Node 风格的回调。

type Listener = (error: Error, state: Object) => void
type Middleware = (next: Listener) => Listener

中间件的一个重要特性是它们是可组合的：

// Middlewares 1, 2, and 3 will run in sequence from left to right
const combinedMiddleware = compose(middleware1, middleware2, middlware3)

路由器中间件很像 Redux 中的中间件。 它用于在状态对象通过路由器时扩充状态对象。 下面是一个添加 query 字段的中间件示例：

import queryString from 'query-string'

const parseQuery = next => (error, state) => {
  if (error) return next(error)

  next(null, {
    ...state,
    query: queryString.parse(state.search)
  })
}

与 React props 和 Redux 状态一样，我们将路由器状态视为不可变的。

State object conventions

所有状态对象都应具有字段 path、pathname、search 和 hash。 当您将路径字符串传递给路由器函数时，将从路径中提取其余字段。 反之亦然：如果您将初始状态对象传递给具有 pathname、search 和 hash 的路由器函数，而不是路径字符串，添加了一个 path 字段。 这允许中间件依赖于这些字段而无需进行自己的解析。

还有两个具有特殊含义的附加字段：redirect 和 done。 redirect 是不言自明的：中间件应该跳过任何带有 redirect 字段的状态对象，将其传递给下一个中间件。 类似地，带有done: true 的状态对象表示之前的中间件已经处理过它，不需要其他中间件进一步处理。 （在某些情况下，中间件可能适合处理 done 状态对象。）

处理所有这些特殊情况可能会变得乏味。 handle() 允许您创建处理特定情况的中间件。 它有点像 switch 语句或模式匹配。 示例

import { handle } from '@acdlite/router'

const middleware = handle({
  // Handle error
  error: next => (error, state) => {...}

  // Handle redirect
  redirect: next => (error, state) => {...}

  // Handle done
  done: next => (error, state) => {...}

  // Handle all other cases
  next: next => (error, state) => {...}
})

next() 是最常见的处理程序。

如果省略处理程序，则默认行为是将状态对象传递给下一个中间件，不变。

Proof-of-concept: React Router-like API

作为概念验证，react-router/ 目录包含用于使用中间件实现类似 React Router API 的实用程序。 它支持：

• Nested route matching, with params
• Plain object routes or JSX routes
• Asynchronous route fetching, using config.getChildRoutes()
• Asynchronous component fetching, using config.getComponent()
• Index routes

尚未完成：

• <Redirect> routes

在内部，它使用了 React Router 的几种方法，因此路由匹配行为应该是相同的。

示例：

import { createRouter } from '@acdlite/router'
import { nestedRoute, getComponents, Route, IndexRoute } from '@acdlite/router/react-router'
import createHistory from 'history/lib/createBrowserHistory'

const reactRouter = createRouter(
  nestedRoute(
    <Route path="/" component={App}>
      <Route path="post">
        <IndexRoute component={PostIndex} />
        <Route path=":id" component={Post} />
      </Route>
    </Route>
  ),
  getComponents,
  // ... add additional middleware, if desired
)

const history = createHistory()

// Listen for location updates
history.listen(location => {
  // E.g. after navigating to '/post/123'
  // Routers can accept either a path string or an object with `pathname`,
  // `query`, and `search`, so we can pass the location object directly.
  reactRouter(location, {
    // Route was successful
    done: (error, state) => {
      // Returns a state object with info about the matched routes
      expect(state).to.eql({
        params: { id: '123' },
        routes: [...] // Array of matching route config objects
        components: [App, Post], // Array of matching components
        // ...plus other fields from the location object
      })

      // Render your app using state...
    },

    // Handle redirects
    redirect: (error, state) => {
      history.replace(state.redirect)
    },

    // Handle errors
    error: error => {
      throw error
    }
  }
})

需要注意的一个关键点是服务器端 API 完全相同：不使用历史记录，只是将路径字符串直接传递给路由器，并实现 done(), redirect() 和 error() 视情况而定。

另请注意，历史记录与您的路由逻辑之间没有相互依赖关系。

路由器返回匹配的组件，但您可以根据自己的喜好渲染它们。 一个简单的开始方法是使用 Recompose 的 nest() 功能：

const Component = nest(...state.components)
ReactDOM.render(<Component {...state.params} {...state.query} />)

这让你 90% 的方式与 React Router 保持一致。 组件和转换挂钩等便利设施需要重新实现，但相当简单。