大师兄

最近在做运营侧中台项目的重构，目前的选型是 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<any>

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 真香！

参考书籍

在 GitHub 上编辑此页2023/9/23 16:50:18