typescript 支持与本地调试

typescript 支持与本地调试

前言

在上一章节,我们创建了一个 hello world 函数,并把它顺利的部署到了AWS云上。然而真正上生产的函数项目肯定不会这么简单。

对于一个现代的 nodejs 项目来说,我们还有许多的需求:

比如我们也更想使用 typescript 来进行开发,还有我们也需要在本地搭建一套完整的模拟环境,来对我们编写的代码进行调试和测试。

比如我们要添加对应的单元测试和 CI/CD

又或者是我们的函数里面,各种第三方的依赖项的处理,js 相关的还好,但是其他那些和平台绑定的 二进制文件,又或者是内置的 .xdb 等等一些数据文件,应该如何处理呢?请听我娓娓道来.

支持 typescript

我们想要用 ts 来编写函数进行调试和部署,幸运的是 serverless 为我们提供了开箱即用的插件:

  1. serverless-plugin-typescript, 这是由 serverless 官方维护的 ts 支持方案,推荐使用
  2. serverless-esbuild,这是第三方编写的,使用 esbuild 去编译 ts 代码的方案

当然,除了插件方案之外,当然也有非 serverless 插件的传统打包方案,即直接使用 tsc 或者 webpack/rollup/esbuild 又或者进一步封装的 tsup/unbuild 等等这些工具,直接构建出 dist 产物,然后 sls deploy 直接部署 dist 里代码文件的方案。

这个传统打包方案,我们下一篇文章《serverless nodejs 项目打包最佳实践》会详细介绍。

这些插件的用法非常简单,我们只需要在安装它们之后,再把它们注册进你的 serverless.yml 文件中就可以了。

比如 serverless-plugin-typescript, 我们先安装 npm i -D serverless-plugin-typescript

然后在 serverless.yml 中注册:

# 注册插件,传入一个数组
plugins:
  - serverless-plugin-typescript
# 插件传入的 options 都在这个字段下
custom:
  # 可以不传值,不传默认值见 https://www.npmjs.com/package/serverless-plugin-typescript
  serverlessPluginTypescript:
    tsConfigFileLocation: "./tsconfig.build.json"

接下来执行 sls packge 命令(sls deploy的前置打包成压缩包步骤),插件就会自己去找当前目录下的 tsconfig.build.json(上面tsConfigFileLocation指定的路径)配置,去编译 ts 代码,然后打入将被上传的压缩包里。

打包后,你可以在你配置的 tsconfigoutDir 目录下,找到编译生成的结果,并进行校验。

函数的本地调试

我们本地环境,去调试编写的云函数,比较方便的做法,主要有 2 种:

  1. 一种为执行 sls invoke local -f -d/-p ... 进行直接调试
  2. 另外一种为通过 serverless-offline 插件,在本地构建出模拟的 lambdaapi网关环境 进行调试,显然这种调试方式非常适合 web 服务。
注意,因为整个项目是 typescript 编写的,而实际运行却是 js 文件,所以你编译时,必须打开 sourcemap 选项才能命中到 ts源码里的断点,不然只能把断点命中到 .build/.esbuildjs 产物的代码。

启用 node-terminal 调试

这个方式很简单,因为 node-terminal 开箱即用的,

  1. 一种方法,我们直接在 vscode 下方的终端窗口,点击加号旁边的下拉icon,添加 JavaScript 调试终端,然后再cd到目标目录中,执行对应的调试 npm script 即可。
  2. 另外一种方法是利用 .vscode/launch.json 去维护我们的调试脚本,同时在 vscode debug 界面进行调试。

配置类似于下方:

{
  "version": "0.2.0",
  "configurations": [
    {
      "command": "npm run invoke:local",
      "name": "[hello-world] invoke local",
      "request": "launch",
      "type": "node-terminal",
      "cwd": "${workspaceFolder}/apps/hello-world"
    },
    {
      "command": "npm run offline",
      "name": "[hello-world] offline",
      "request": "launch",
      "type": "node-terminal",
      "cwd": "${workspaceFolder}/apps/hello-world"
    }
  ]
}

下方章节的 invoke localserverless-offline 都直接使用上述的 vscode 配置示例进行调试。

invoke local

sls invoke local -f -d/-p ... 这个命令是直接调用本地函数进行调试.

其中 function name 是函数名,也就是我们在 serverless.yml 中注册的名字。

后面加的 -d/-p 用来控制传入的 event 对象。

-d--data 的缩写,代表直接把跟在后面的字符串作为 json 传入函数进行调用。

-p(--path的缩写)其实功能类似,不过 -p 是传入一个 json 文件的路径作为参数,读取之后传入函数进行调用,所以我更推荐使用 -p

serverless-offline

serverless-offline 插件是在本地模拟出一个 lambdaAPI Gateway 的环境进行部署,再起一个 http server 监听端口,这样来进行调试。

这种调试方法,其实和我们调试 express/koa 项目是非常类似的。不同的是,我们的路由不在我们的代码里进行注册,而在于 serverless.yml 里函数对应网关的配置。

serverless-offline 插件注册也非常的简单:

# 注册插件
plugins:
  - serverless-offline

custom:
# 修改配置项
  serverless-offline:
    noPrependStageInUrl: true
    noAuth: true

注册完成之后,使用 sls offline 命令,即可启动,看到:

Offline [http for lambda] listening on http://localhost:3000
Function names exposed for local invocation by aws-sdk:
           * hello: aws-http-api-ts-dev-hello

   ┌─────────────────────────────────────────────────────────────────────────┐
   │                                                                         │
   │   GET | http://localhost:3000/                                          │
   │   POST | http://localhost:3000/2015-03-31/functions/hello/invocations   │
   │                                                                         │
   └─────────────────────────────────────────────────────────────────────────┘

Server ready: http://localhost:3000 

出现上述结果,代表已经启动完成,此时它的调试也只需要像我们调试 express/koa/nest 那样,直接在 vscode 里打断点,即可命中。

Next Chapter

现在你已经学会了如何在本地调试代码和用 typescript 来编写函数了。

下一篇,《依赖项的处理与层的创建与注册》中,将会详细解释依赖项的处理,欢迎阅读。

完整示例及文章仓库地址

https://github.com/sonofmagic/serverless-aws-cn-guide

如果你遇到什么问题,或者发现什么勘误,欢迎提 issue 给我

你可能感兴趣的:(typescript 支持与本地调试)