wok-server 0.1.0

package/documentation/zh-cn/mongodb.md

@@ -0,0 +1,262 @@
+# mongodb
+
+mongodb 组件基于 [mongodb 官方的驱动](https://www.npmjs.com/package/mongodb)进行封装，提供了简单的实体映射和增删改查功能，以方便操作。
+
+## 环境变量
+
+mongodb 组件支持多实例，默认情况下以 MONGO 为前缀。
+
+| 变量名称                    | 说明                                                            |
+| :-------------------------- | :-------------------------------------------------------------- |
+| MONGO_URI                   | mongo 链接，示例：mongodb+srv://<user>:<password>@<cluster-url> |
+| MONGO_MAX_POOL_SIZE         | 连接小事情最大连接数,默认 10                                    |
+| MONGO_MIN_POOL_SIZE         | 连接小事情最小连接数,默认 1                                     |
+| MONGO_MAX_CONNECTING        | 连接池最大并发连接数 ,默认 10                                   |
+| MONGO_MAX_IDLE_TIME_MS      | 连接的最大闲置时间,单位毫秒,默认 60000                          |
+| MONGO_WAIT_QUEUE_TIMEOUT_MS | 连接的最大等待时间,单位毫秒,默认 60000                          |
+| MONGO_SLOW_QUERY_WARN       | 慢查询警告，开启后会对慢查询输出警告日志，默认开启              |
+| MONGO_SLOW_QUERY_MS         | 慢查询毫秒数,默认 200                                           |
+| MONGO_TRANSACTION_TIMEOUT   | 事务超时时间，单位毫秒，默认 5000                               |
+| MONGO_TRANSACTION_STRICT    | 事务严格模式,默认为 true ,设置为 false 关闭                     |
+
+## 使用
+
+### 初始化
+
+先使用函数 enableMongoDB 来启用 mongodb ，完成后才使用相关的功能。
+
+```ts
+await enableMongoDB()
+```
+
+组件支持多实例，如果有多个库需要连接，可以指定一个新名称。
+
+```ts
+// 启用指定名称为 md2 的实现
+await enableMongoDB('md2')
+```
+
+默认情况下环境变量的前缀是 MONGO，指定名称的实例，将使用名称大写后的前缀，上例中指定的名称为 md2 的实例，将使用前缀 MD2。
+
+```
+# 配置默认的连接
+MONGO_URI=mongodb://test1:t1abcd@localhost/t1
+MONGO_MAXPOOLSIZE=10
+# 配置 md2 名称对应的链接
+MD2_URI=mongodb://test2:t2abcd@localhost/t2
+MD2_MAXPOOLSIZE=10
+```
+
+使用 getMongoDBManager 函数可以获取一个管理器实例用于操作 mongodb 实例，
+支持可选的名称来获取对应的实例。
+
+```ts
+// 默认实例
+const mananger = getMongoDBManager()
+// md2 实例
+const md2 = getMongoDBManager('md2')
+```
+
+### 实体映射
+
+通过 manager 对象提供的方法可以完成基础的增删改查，但是在操作之前必须要进行配置。
+
+配置分为两个部分，一个是集合的数据格式定义，一个是集合信息的设定，下面是一个示例。
+
+```ts
+/**
+ * 用户集合数据定义。
+ * 主键名称固定为 _id，不支持映射配置，实体类不要有 _id 字段。
+ */
+export interface User {
+  nickname: string
+  skills: string[]
+  // 创建和更新字段都可以设置让组件自动维护
+  // 因为类型约束的缘故，为了插入和更新时不填，这里设为可选
+  createAt?: Date
+  updateAt?: Date
+}
+/**
+ * 用户集合信息，类型是 MongoCollection，泛型就是实体类型。
+ * 主键名称固定为 _id，不支持映射配置。
+ */
+export const collUser: MongoCollection<User> = {
+  /**
+   * 集合名称
+   */
+  collectionName: 'user',
+  /**
+   * 配置创建时间字段，组件会自动管理
+   */
+  createdDate: {
+    type: 'date',
+    field: 'createAt'
+  },
+  /**
+   * 配置更新时间字段，组件会自动管理
+   */
+  updatedDate: {
+    type: 'date',
+    field: 'updateAt'
+  }
+}
+```
+
+### 增删改查
+
+现在就可以做增删改查了，manager 的所有操作第一个参数都是集合信息，就是前面配置的 collUser。
+
+```ts
+const mananger = getMongoDBManager()
+// 插入记录，在插入记录时，如果 _id 无值，则会由数据库生成 ObjectId 的主键值
+await mananger.insert(collUser, { _id: '007', nickname: 'Spark', skills: [] })
+// 按id 查找
+const uer1 = await mananger.findById(collUser, '007')
+// 更新昵称
+user1.nickname = 'ryan'
+await mananger.update(collUser, user1)
+// 判定某个 id 是否存在
+const exist = await mananger.existsById(collUser, 'xyz')
+// 判定指定条件是否有记录存在
+const exist2 = await mananger.existsBy(collUser, { nickname: 'acute' })
+// 按 id 删除
+await mananger.deleteById(collUser, '007')
+// 按条件删除，慎用，一次性删除大量数据很可能会导致数据库高负载，引发线上事故
+await mananger.deleteMany(collUser, { nickname: 'smith' })
+// 查找第一条符合条件的记录
+const jack = await mananger.findFirst(collUser, { nickname: 'jack' })
+// 查询集合中的所有记录，谨慎使用，一次性查询大量数据可能会爆内存，需要很长时间来传输
+await mananger.findAll(collUser)
+// 统计数量，谨慎使用，count 操作即便能走索引，数据量大也会有性能问题
+const count = await mananger.count(collUser, { nickname: 'Steve' })
+// 查找有技能的用户，最多返回2条结果
+const list = await mananger.find(
+  collUser,
+  {
+    skills: { $exists: true }
+  },
+  { offset: 0, limit: 2 }
+)
+// 分页，按id排序，每页20条，查询第2页的记录
+const page = await mananger.paginate(
+  collUser,
+  {
+    skills: { $exists: true }
+  },
+  { pn: 2, pz: 20, orderBy: ['_id', 'asc'] }
+)
+```
+
+### 几种更新方法说明
+
+manager 提供了四种更新方法：update、partialUpdate、updateMany、updateOne。
+
+| 方法名称      | 说明                                                                       |
+| :------------ | :------------------------------------------------------------------------- |
+| update        | 整个文档更新，需要以传递完整的文档信息，返回更新后的文档，更新失败抛出异常 |
+| partialUpdate | 局部更新，只需要传递 id 和要更新的字段信息，返回更新是否成功               |
+| partialUpdate | 局部更新，只需要传递 id 和要更新的字段信息，返回更新是否成功               |
+| updateMany    | 更新所有符合条件的记录，返回被更新文档数量                                 |
+| updateOne     | 只更新一条符合条件的记录，只能是相等条件，不支持范围条件                   |
+
+```ts
+// update 需要有完整的文档，一般都要先查询获取文档
+const user = await mananger.findById(collUser, '007')
+user.nickname = 'ryan'
+await mananger.update(collUser, user)
+// partialUpdate 则不需要
+// 将 id 为 001 的文档昵称更新为 lily
+await manager.partialUpdate(collUser, '001', { $set: { nickname: 'lily' } })
+// updateMany 和 partialUpdate 唯一的区别就是 id 参数变为条件
+// 将所有学分小于等于10的用户学分加一
+await manager.updateMany(collUser, { credit: { $lte: 10 } }, { $inc: { credit: 1 } })
+```
+
+## 版本管理
+
+enableMongoDB 函数支持 migration 参数，用于版本管理，完成自动迁移。
+
+```ts
+await enableMongoDB({
+  migration: {
+    versionList: versionList
+  }
+})
+```
+
+其中的 versionList 是版本列表，格式是元素为 MongoMigrationVersion（`(db: Db) => Promise<void>`） 类型的数组，
+Db 则是 mongodb 驱动提供的库，可以完成各种操作，比如创建集合和索引等。
+版本号就是元素的下标，就是说每次程序有更新都应该增加元素，已经的元素不能做任何修改，程序不会做任何校验。
+在启动阶段，程序会检查已经更新的版本号（版本列表的下标），然后从版本列表中寻找之后的版本，逐个更新并标记已经完成的版本号。
+
+下面是 versionList 参数的示例：
+
+```ts
+const versionList: MongoMigrationVersion[] = [
+  // 版本一
+  async db => {
+    // 创建一个集合，插入点数据 再创建索引
+    await db.createCollection('user')
+    await db
+      .collection<User>('user')
+      .createIndex({ nickname: 1 }, { unique: true, name: 'uk_nickname' })
+    await db
+      .collection<User>('user')
+      .createIndex({ skills: 1 }, { unique: false, name: 'idx_skills' })
+    // 预置数据
+    await db.collection<User>('user').insertOne({
+      nickname: 'jack',
+      skills: ['java'],
+      createAt: new Date(),
+      updateAt: new Date()
+    })
+  },
+  // 版本二
+  async db => {
+    // 删除一个索引
+    await db.collection<User>('user').dropIndex('idx_skills')
+    // 预置数据
+    await db.collection<User>('user').insertOne({
+      nickname: 'tom',
+      skills: ['golang', 'rust'],
+      createAt: new Date(),
+      updateAt: new Date()
+    })
+  }
+]
+```
+
+## 事务
+
+使用 mananger 对象的 tx 方法可以执行事务操作，方法接受一个函数参数，函数的参数是 session 对象，
+**所在事务中的操作，都必须调用 session 的方法，session 的操作方法与 mananger 是一样的**。
+
+```ts
+await manager.tx(
+  async session => {
+    // 在事务中更新订单和帐号余额
+    // orderId 订单ID
+    // accountId 帐号ID
+    // amount 订单金额
+    await session.partialUpdate(collOrder, orderId, { $set: { status: 'finished' } })
+    await session.partialUpdate(collAccount, accountId, { $inc: { balance: -amount } })
+  },
+  // 额外的选项，可针对单个事务设置超时时间等
+  { timeout: 1000 }
+)
+```
+
+### 严格模式
+
+事务默认是打开严格模式的，在严格模式下，事务中的很多操作都被禁止，
+通过将环境变量 MONGO_TRANSACTION_STRICT （默认变量名称，多实例的情况下使用对应名称）
+设置为 false 可以关闭。
+
+严格模式下，禁止在事务中进行以下的操作：
+
+1. 批量插入 insertMany
+2. 批量更新 updateMany
+3. 批量删除 deleteMany
+4. 批量查询和计数 find、count、paginate
+5. findByIdIn 参数超过 100 个
+6. 调用 session 进行的任何操作累计超过 10 次

package/documentation/zh-cn/mvc.md

@@ -0,0 +1,430 @@
+# MVC
+
+mvc 组件基于 Nodejs 自带的 http 模块，让搭建 http 服务，处理请求更方便。
+
+### 环境变量
+
+| 环境变量                  | 说明                                             |
+| :------------------------ | :----------------------------------------------- |
+| SERVER_PORT               | 端口号                                           |
+| SERVER_TIMEOUT            | 超时时间，单位毫秒，默认 30000                   |
+| SERVER_ACCESS_LOG         | 是否启用访问日志，默认不启用，值为 true 表示启用 |
+| SERVER_CORS_ALLOW_ORIGIN  | 跨域允许的源域名，默认 \*                        |
+| SERVER_CORS_ALLOW_HEADERS | 跨域允许的消息头，默认 \*                        |
+| SERVER_CORS_ALLOW_METHODS | 跨域允许的请求方法，默认 \*                      |
+
+### 开始使用
+
+```ts
+// 启动服务
+await startWebServer({
+  // 路由，实际开发中页面很多的情况下，可以将每个路由处理函数单独写在一个文件中
+  routers: {
+    '/': async exchange => exchange.respondText('Hello world !')
+  },
+  // 拦截器，可以做授权校验、异常处理等
+  interceptors: [
+    async (exchange, next) => {
+      // 示例场景： http 基本认证
+      if (!validateAuth(exchange.request.headers.authorization)) {
+        // 校验失败响应信息提示浏览器用户需要登录
+        exchange.respond({
+          statusCode: 401,
+          headers: { 'www-Authenticate': 'Basic realm= "family"' }
+        })
+        return
+      }
+      // 调用 next 函数继续后面的流程
+      await next()
+    }
+  ]
+})
+```
+
+启动服务主要需要设置两个参数，一个是路由，一个是拦截器。路由用于处理具体的请求，拦截器可以在路由执行前执行，
+对请求进行拦截，下面会细说。
+
+在有需要的时候，也可以停止服务。
+
+```ts
+// 停止服务
+await stopWebServer()
+```
+
+### 路由
+
+路由的配置是键值对，键是路径，值是异步处理函数，函数接收一个一个参数 exchange ，类型是 ServerExchange,
+提供了读取请求信息和一些响应常见格式的方法。
+
+```ts
+await startWebServer({
+  // 路由
+  routers: {
+    '/': async exchange => {
+      // 通过 exchage 获取请求信息
+      const url = exchange.request.url
+      const method = exchange.request.method
+      const referer = exchange.request.headers.referer
+      // 读取正文
+      const body = await exchange.bodyJson()
+      // 响应信息
+      exchange.respondJson({ ok: true })
+    },
+    '/users': async exchange => {
+      const list = await listUser()
+      exchange.respondJson(list)
+    },
+    '*': async exchange => {
+      exchage.respondText(`404 Not Found`, 404)
+    }
+  }
+})
+```
+
+`*` 是一个特殊的路径，用于自定义 404 页面，可以处理所有匹配路径失败的请求。
+在未设置 404 页面的情况下，默认返回一个 json 格式的错误提示。
+
+**路由的路径目前仅支持明确地址，不支持模糊路径，不能在路径上绑定变量**，比如 `/users/:id` 这种将用户 id
+作为路径的一部分，是无法处理的。出于程序的开销方面的考虑，没有支持，后续的版本有可能会考虑。
+
+### 拦截器
+
+拦截器的配置是一个列表，每个拦截器都是一个异步函数，函数接收两个参数：exchange 和 next 。
+exchange 是 ServerExchange 类型，与上面路由中的 exchage 是一样的。
+next 是一个无参异步函数，调用 next 执行后面的流程（下一个拦截器或路由）。
+
+```ts
+// 启动服务
+await startWebServer({
+  // 路由
+  routers: {
+    // 省略路由配置代码
+  },
+  // 拦截器，可以做授权校验、异常处理等
+  interceptors: [
+    async (exchange, next) => {
+      // 获取原生的请求和响应对象
+      const { request, response } = exchange
+      const url = request.url
+      const userAgent = request.headers['user-agent']
+      const ip = request.socket.remoteAddr
+      try {
+        // 调用 next 函数继续后面的流程
+        await next()
+      } catch (e) {
+        // 演示场景：在拦截器里统一处理校验失败发生的异常
+        if (e instanceof ValidationException) {
+          // 调用 exchange 上的工具方法，快速完成一个响应
+          exchange.respondErrMsg(e.errMsg, 400)
+          return
+        }
+        getLogger().error(`接口异常 ${url}`, e)
+        // 调用 exchange 上的工具方法，快速完成一个响应
+        exchange.respondErrMsg('服务器内部错误', 500)
+      }
+    }
+  ]
+})
+```
+
+### 针对不同的方法进行处理
+
+组件提供了 restful 函数，可以在配置路由时按请求方法进行分发。
+
+```ts
+// 启动服务
+await startWebServer({
+  // 路由
+  routers: {
+    '/users': restful({
+      get: async exchange => {
+        // 处理 get 请求
+      },
+      post: async exchange => {
+        // 处理 post 请求
+      },
+      delete: async exchange => {
+        // 处理 delete 请求
+      }
+    })
+  }
+})
+```
+
+注意：路由目前并不支持 restful 风格的动态路径，前面已经有说明。
+
+### json 请求处理
+
+框架自带了函数 createJsonHandler 可以方便的创建一个处理 json 请求的的 RouterHandler，
+请求和响应都是 json 格式，响应和请求都可以为空。请求为空可以填入类型 {} 来表示空对象，响应为空可以填入类型 void 。
+
+```ts
+// 申请请求体　json 格式和响应的格式
+interface Form {
+  name: string
+  age: number
+}
+interface Resp {
+  id: string
+}
+
+export const userCreateHandler = createJsonHandler<Form, Resp>({
+  /**
+   * 请求正文映射对象校验规则，可选.
+   */
+  validation: {
+    name: [notBlank('名称不能为空'), length({ min: 2, max: 16, message: '名称必须是2-16个字' })],
+    age: [notNull('年龄必填'), min(2), max(16)]
+  },
+  async handle(body, exchange) {
+    // 获取授权信息
+    const { authorization } = exchange.headers
+    const currentUser = await findUserByAuth(authorization)
+    console.log(`姓名是：${body.name}`)
+    console.log(`年龄是：${body.age}`)
+    const newUser = await createUser(body)
+    return { id: newUser.id }
+  }
+})
+```
+
+校验时会自动根据消息头 `accept-language` 切换校验器的语言，对于没有自定义错误信息的校验使用切换后的语言给予默认的提示。
+
+### 上传文件处理
+
+组件目前尚未实现对 multipart/form-data 类型请求的处理，如有需要可通一些第三方库来解析文件上传的请求内容。
+
+下面是通过 formidable 这个库来解析请求的示例：
+
+```ts
+// 启动服务
+import formidable from 'formidable'
+
+await startWebServer({
+  // 路由
+  routers: {
+    '/cover': async exchange => {
+      const form = formidable({})
+      // 解析请求内容
+      const [fields, files] = await form.parse(exchage.request)
+      // todo 继续业务处理
+    }
+  }
+})
+```
+
+如果使用了其它的库来读取 request 内容，则不能再使用 exchange 中的 bodyXxx 系列方法，调用时会抛出异常。
+同时在调用了 bodyXxx 系列方法后也不能再调用其它的库来读取内容，否则将读取不到完整内容或引发异常。
+但是 bodyXxx 系列方法是可以重复调用的，不会产生错误，调用过 bodyText 方法后再调用 bodyJson 是可以的。
+
+### 响应 html
+
+ServerExchange 类型提供了 respondHtml 方法，用于渲染 html，简单的组织标签层级和进行动态的结构构建。
+
+```ts
+// 启动服务
+await startWebServer({
+  // 路由
+  routers: {
+    '/profile': async exchange => {
+      // 获取用户信息
+      const user = await getUser(exchange.headers.authorization)
+      // html 结构组织的逻辑可能会很长，复杂业务可以提取成为单独的函数
+      exchange.respondHtml({
+        lang: 'zh',
+        head: [
+          // 为 head 添加标签，这里添加一个 title
+          // children 中直接写字符串代表 TextNode
+          { tag: 'title', children: ['个人中心'] },
+          { tag: 'script', attrs: { type: 'module', src: 'main.js' } }
+        ],
+        body: {
+          // 属性，属性是有类型推断的，可以对 html 的全局属性进行提示, 如 style、id、class 等
+          attrs: {
+            // style 是有类型推断的
+            style: { 'background-color': 'white' }
+          },
+          // children 也可以接收一个函数，函数的参数是一个添加子元素的函数
+          // 这样可以结合循环和分支控制来实现动态渲染效果
+          children: add => {
+            add({ tag: 'h1', children: ['个人中心'] })
+            // 在 user 有值和无值的情况下分别渲染不同的元素
+            if (user) {
+              1
+              add({ tag: 'p', children: [`用户名：${user.account}`] })
+            } else {
+              add({
+                tag: 'p',
+                children: [
+                  '请登录后查看',
+                  { tag: 'a', attrs: { href: '/login' }, children: ['点击进行登录'] }
+                ]
+              })
+            }
+            // 对于一些常用的组合，可以封装成一个函数，返回 HtmlTag 类型
+            // 这里的 footer 就是这样一个例子
+            add(footer())
+          }
+        }
+      })
+    }
+  }
+})
+```
+
+footer 函数示例：
+
+```ts
+function footer(): HtmlTag {
+  return {
+    tag: 'div',
+    attrs: { class: 'footer' },
+    children: [
+      { tag: 'a', attrs: { href: '/about' }, children: ['关于我们'] },
+      { tag: 'a', attrs: { href: '/call' }, children: ['联系我们'] },
+      { tag: 'a', attrs: { href: '/privacy' }, children: ['隐私协议'] }
+    ]
+  }
+}
+```
+
+如果不喜欢框架自带的 html 渲染模式，也可以使用一些第三方的模板渲染组件。
+
+下面是使用库 handlebars 来渲染的的示例：
+
+```ts
+import { compile } from 'handlebars'
+
+await startWebServer({
+  // 路由
+  routers: {
+    '/html': async exchange => {
+      const source =
+        '<!DOCTYPE html>' +
+        '<html>' +
+        '<head>' +
+        '<title>Handlebars Example</title>' +
+        '</head>' +
+        '<body>' +
+        '<p>Hello, my name is {{name}}. I am from {{hometown}}. I have ' +
+        '{{kids.length}} kids:</p>' +
+        '<ul>{{#kids}}<li>{{name}} is {{age}}</li>{{/kids}}</ul>' +
+        '</body>' +
+        '</html>'
+      // 编译模板
+      const template = compile(source)
+      // 数据
+      const data = {
+        name: 'Alan',
+        hometown: 'Somewhere, TX',
+        kids: [
+          { name: 'Jimmy', age: '12' },
+          { name: 'Sally', age: '4' }
+        ]
+      }
+      // 构建内容
+      const result = template(data)
+      // 渲染构建好的 html 字符串
+      exchange.respondHtml(result)
+    }
+  }
+})
+```
+
+下面是使用库 vue 3.x 的 ssr 来渲染 html 的示例，
+
+```ts
+import { createSSRApp } from 'vue'
+import { renderToString } from 'vue/server-renderer'
+
+await startWebServer({
+  // 路由
+  routers: {
+    '/html': async exchange => {
+      const app = createSSRApp({
+        data: () => ({ count: 1 }),
+        template: `<button>{{ count }}</button>`
+      })
+      const html = await renderToString(app)
+      // 渲染页面，将生成的 html 嵌入页面
+      exchange.respondHtml(`<!DOCTYPE html>
+    <html>
+      <head>
+        <title>Vue SSR Example</title>
+      </head>
+      <body>
+        <div id="app">${html}</div>
+      </body>
+    </html>`)
+    }
+  }
+})
+```
+
+### 静态文件
+
+通过 static 参数可以设置静态文件目录映射，将一个目录映射到请求路径。
+
+```ts
+await startWebServer({
+  static: {
+    '/a': { dir: 'D:\\Download', cacheAge: 300 },
+    '/a/b': { dir: 'E:\\Dowload', cacheAge: 150 },
+    '/b': { dir: 'static', cacheAge: 0 }
+  },
+  routers: {}
+})
+```
+
+dir 参数是映射文件目录的地址，可以是绝对路径，也可以是相对路径，相对路径会从进程的当前目录下找。cacheAge 参数
+是缓存时间，如果设置了大于０的值，则会根据设定生成消息头 Cache-Control。
+
+请求路径仅支持前缀匹配，不支持通配符，比如 /a/demo.html 可以匹配 /a 路径，响应配置的文件目录下的 demo.html 文件。
+路径配置是有优先级的，如果访问 /a/b/music.mp3 则会匹配到 /a/b 的配置，而不是 /a ，因为 /a/b 的配置更详细，优先级也更高，
+并且如果从 /a/b 配置的目录下没有找到文件，也不会再尝试 /a 的配置。
+
+静态文件同时也支持主页自动映射，比如访问 /a/b/c ，会匹配到 /a/b 的配置，然后在配置的文件目录下寻找文件 c ，
+如果找不到则尝试寻找目录 c 下的 index.html 文件。
+
+### 请求日志
+
+通过将环境变量 SERVER_ACCESS_LOG 设置为 true 可以开启请求日志，开启后会在每次响应完成后输出请求和响应信息到日志里，默认是关闭的。
+
+```
+[2023/10/25 17:09:47.872][INFO][access-log]{"method":"GET","url":"/html?tab=%E6%9C%8D%E8%A3%85","ip":"::ffff:127.0.0.1","start":"2023/10/25 17:09:47.871","rt":1,"status":200}
+```
+
+组件仅提供了简单的 json 格式信息输出，不支持配置格式。如有请求统计的需要，可考虑自定义拦截器
+将请求信息存入消息队列或数据库再做计算，也可以分析日志提取请求信息。
+
+### websocket
+
+组件本身没有提供 websocket 处理的功能，但是 startWebServer 函数提供了参数 preHandler
+可以对服务进行前置处理，在服务没有启动前完成一些额外的操作，这样可以整合其它支持原生 http 模块的库。
+
+可通过整合 socket.io 这个库来实现对 websocket 的处理。
+
+```ts
+import { Server } from 'socket.io'
+await startWebServer({
+  routers: {
+    // 路由配置省略...
+  },
+  // 前置处理，连接 socket.io
+  preHandler: async server => {
+    const io = new Server(server)
+    // 适配 /chat 路径，如果路由中也有 /chat 路径，不会冲突
+    // 客户端用 http 协议请求会被路由处理
+    // 当然，肯定不推荐这么做
+    io.of('/chat').on('connection', socket => {
+      // 建立连接后在回调中完成会话的管理和业务处理
+      socket.on('message', data => {
+        /* 处理自定义事件*/
+      })
+      socket.on('disconnect', () => {
+        /* 连接断开处理 */
+      })
+    })
+  }
+})
+```