当Koa遇上Typescript

  • Post author:
  • Post category:其他


   最近在做运营侧中台项目的重构,目前的选型是 koa2+typescript。在实际生产中,切实体会到了 typescript 类型带来的好处。

为了更形象说明 typescript 的优势,还是先来看一个场景吧:


BUG 现场


作为一门灵活度特别大的语言,坏处就是:

复杂逻辑编写过程中,数据结构信息可能由于逻辑复杂、人员变更等情况而丢失,从而写出来的代码含有隐含错误

比如这次我在给自己的博客编写node 脚本的时候就遇到了这种情况:

const result = [];

function findAllFiles(root) {
  const files = fs.readdirSync(root);
  files.forEach(name => {
    const file = path.resolve(root, name);
    if (isFolder(file)) {
      findAllFiles(file);
    } else {
      result.push({
        path: file,
        check: false,
        content: fs.readFileSync(file)
      });
    }
  });
}

result 保存了递归遍历的所有文件的 path、check、content 信息,其中 content 信息会被传给prettier.js的check(content: string, options: object)方法。

显然,上述代码是有错误的,但是极难发现。只有运行它的时候,才能通过堆栈报错来进行定位。但如果借助 ts,就可以立即发现错误,保持代码稳健。

这个问题放在文章最后再说,下面看看 ts 在 koa 项目中的运用吧。


项目目录


由于没有历史包袱,整个项目的架构还是非常清爽的。如下所示:

.
├── README.md
├── bin # 存放scripts的脚本文件
├── dist # 编译打包后的js文件
├── docs # 详细文档
├── package.json # npm
├── sh # pm2等脚本
├── src # 项目源码
├── tmp # 存放临时文件的地方
└── tsconfig.json # typescript编译配置


typescript 编译与 npm 配置

因为是用 ts 来编写代码,因此需要专门编写 typescript 的配置文件:tsconfig.json。根据个人习惯,以及之前组内的 ts 项目,配置如下:

{
  "compilerOptions": {
    "module": "commonjs", // 编译生成的模块系统代码
    "target": "es2017", // 指定ecmascript的目标版本
    "noImplicitAny": true, // 禁止隐式any类型
    "outDir": "./dist",
    "sourceMap": false,
    "allowJs": false, // 是否允许出现js
    "newLine": "LF"
  },
  "include": ["src/**/*"]
}

对于一些有历史遗留的项目,或者说用 js 逐步重构为 ts 的项目来说,由于存在大量的 js 遗留代码,因此allowJs这里应该为true,noImplicitAny应该为false。

在package.json中,配置两个脚本,一个是 dev 模式,另一个是 prod 模式:

{
  "scripts": {
    "dev": "tsc --watch & export NODE_ENV=development && node bin/dev.js -t dist/ -e dist/app.js",
    "build": "rm -rf dist/* && tsc"
  }
}

在 dev 模式下,需要 tsc 监听配置中include中指定的 ts 文件的变化,并且实时编译。bin/dev.js是根据项目需要编写的监听脚本,它会监听dist/目录中编译后的 js 文件,一旦有满足重启条件,就重启服务器。


类型声明文件

koajs 与常见插件的类型声明都要在@types 下安装:

npm i --save-dev @types/koa @types/koa-router @types/koa2-cors @types/koa-bodyparser


区分 dev/prod 环境

为了方便之后的开发和上线,src/config/目录如下:

.
├── dev.ts
├── index.ts
└── prod.ts

配置分为 prod 和 dev 两份。dev 模式下,向控制台打印信息;在 prod 下,需要向指定位置写入日志信息。类似的,dev 下不需要进行身份验证,prod 下需要内网身份验证。因此,利用 ts 的extends特性来复用数据声明:

// mode: dev
export interface ConfigScheme {
  // 监听端口
  port: number;
  // mongodb配置
  mongodb: {
    host: string;
    port: number;
    db: string;
  };
}
// mode: prod
export interface ProdConfigScheme extends ConfigScheme {
  // 日志存储位置
  logRoot: string;
}

在 index.ts 中,通过process.env.NODE_ENV变量值来判断模式,进而导出对应的配置。

import { devConf } from "./dev";
import { prodConf } from "./prod";

const config = process.env.NODE_ENV === "development" ? devConf : prodConf;

export default config;

如此,外界直接引入即可。但在开发过程中,例如身份认证中间件。虽然 dev 模式下不会开启,但编写它的时候,引入的config类型是ConfigScheme,在访问ProdConfigScheme上的字段时候 ts 编译器会报错。

这时候,ts 的断言就派上用场了:

import config, { ProdConfigScheme } from "./../config/";

const { logRoot } = config as ProdConfigScheme;


中间件编写


对于整体项目,和 koa 关联较大的业务逻辑主要体现在中间件。这里以运营系统必有的「操作留存中间件」的编写为例,展示如何在 ts 中编写中间件的业务逻辑和数据逻辑。

引入 koa 以及编写好的轮子:

import * as Koa from "koa";
import { print } from "./../helpers/log";
import config from "./../config/";
import { getDB } from "./../database/mongodb";

const { mongodb: mongoConf } = config; // mongo配置
const collectionName = "logs"; // 集合名称


操作留存中需要留存的数据字段有:

staffName: 操作人
visitTime: 操作时间
url: 接口地址
params: 前端传来的所有参数

ts 中借助 interface 直接约束字段类型即可。一目了然,对于之后的维护者来说,基本不需要借助文档,即可理解我们要和 db 交互的数据结构。

interface LogScheme {
  staffName: string;
  visitTime: string;
  url: string;
  params?: any;
}

最后,编写中间件函数逻辑,参数需要指明类型。当然,直接指明参数是 any 类型也可以,但这样和 js 就没差别,而且也体会不到 ts 带来文档化编程的好处。

因为之前已经安装了@types/koa,因此这里不需要我们手动编写 .d.ts 文件。并且,koa 的内置数据类型已经被挂在了前面 import 进来的Koa上了(是的,ts 帮我们做了很多事情)。上下文的类型就是 Koa.BaseContext,回调函数类型是() => Promise

async function logger(ctx: Koa.BaseContext, next: () => Promise<any>) {
  const db = await getDB(mongoConf.db); // 从db链接池中获取链接实例
  if (!db) {
    ctx.body = "mongodb errror at controllers/logger";
    ctx.status = 500;
    return;
  }

  const doc: LogScheme = {
    staffName: ctx.headers["staffname"] || "unknown",
    visitTime: Date.now().toString(10),
    url: ctx.url,
    params: ctx.request.body
  };

  // 不需要await等待这段逻辑执行完毕
  db.collection(collectionName)
    .insertOne(doc)
    .catch(error =>
      print(`fail to log info to mongo: ${error.message}`, "error")
    );

  return next();
}

export default logger;


单元函数

这里以一个日志输出的单元函数为例,说一下「索引签名」的应用。

首先,通过联合类型约束了日志级别:

type LogLevel = "log" | "info" | "warning" | "error" | "success";

此时,打算准备一个映射:日志等级 => 文件名称 的数据结构,例如 info 级别的日志对应输出的文件就是 info.log。显然,这个 object 的所有 key,必须符合 LogLevel。写法如下:

const localLogFile: {
  [level in LogLevel]: string | void;
} = {
  log: "info.log",
  info: "info.log",
  warning: "warning.log",
  error: "error.log",
  success: "success.log"
};

如果对于 log 级别的日志,不需要输出到文件仅仅需要打印到控制台。那么localLogFile应该没有log字段,如果直接去掉log字段,ts 编译器报错如下:

Property 'log' is missing in type '{ info: string; warning: string; error: string; success: string; }' but required in type '{ log: string | void; info: string | void; warning: string | void; error: string | void; success: string | void; }'.

根据错误,这里将索引签名字段设置为「可选」即可:

const localLogFile: {
  [level in LogLevel]?: string | void;
} = {
  info: "info.log",
  warning: "warning.log",
  error: "error.log",
  success: "success.log"
};


关于 export


使用export导出复杂对象时候,请加上类型声明,不要依赖与 ts 的类型推断。

index.ts:

import level0 from "./level0";

export interface ApiScheme {
  method: ApiMethod;
  host: string;
}

export interface ApiSet {
  [propName: string]: ApiScheme;
}

export const apis: ApiSet = {
  ...level0
};

level0.ts:

import { ApiSet } from "./index";

// 声明导出对象的数据类型
export const level0: ApiSet = {
  "qcloud.tcb.getPackageInfo": {
    method: "post",
    host: tcb.dataUrl
  },

  "qcloud.tcb.getAlarmRecord": {
    method: "post",
    host: tcb.dataUrl
  }
};


回到开头

回到开头的场景,如果用 typescript,我们会先声明result中每个对象的格式:

interface FileInfo {
  path: string;
  check: boolean;
  content: string;
}

const result: FileInfo[] = [];

此时,你会发现 typescript 编译器已经给出了报错,在 content: fs.readFileSync(file) 这一行中,报错信息如下:

不能将类型“Buffer”分配给类型“string”。

如此,在编写代码的时候,就能立即发现错误。而不是写了几百行,然后跑起来后,根据堆栈报错一行行去定位问题。

仔细想一下,如果是 30 个人合作的大型 node/前端项目,出错的风险会有多高?定位错误成本会有多高?所以,只想说 ts 真香!



版权声明:本文为zsxy2019原创文章,遵循 CC 4.0 BY-SA 版权协议,转载请附上原文出处链接和本声明。