开源软件名称：

开源软件地址：

开源编程语言：

开源软件介绍：

Node - Koa - Typescript Project

The main purpose of this repository is to build a good project setup and workflow for writing a Node api rest in TypeScript using KOA and an SQL DB.

Koa is a new web framework designed by the team behind Express, which aims to be a smaller, more expressive, and more robust foundation for web applications and APIs. Through leveraging generators Koa allows you to ditch callbacks and greatly increase error-handling. Koa does not bundle any middleware within core, and provides an elegant suite of methods that make writing servers fast and enjoyable.

Through Github Actions CI, this boilerplate is deployed here! You can try to make requests to the different defined endpoints and see how it works. The following Authorization header will have to be set (already signed with the boilerplate's secret) to pass the JWT middleware:

HEADER (DEMO)

Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjEiLCJuYW1lIjoiSmF2aWVyIEF2aWxlcyIsImVtYWlsIjoiYXZpbGVzbG9wZXouamF2aWVyQGdtYWlsLmNvbSJ9.7oxEVGy4VEtaDQyLiuoDvzdO0AyrNrJ_s9NU3vko5-k

AVAILABLE ENDPOINTS DEMO SWAGGER DOCS DEMO

When running the project locally with watch-server, being .env file config the very same as .example.env file, the swagger docs will be deployed at: http:localhost:3000/swagger-html, and the bearer token for authorization should be as follows:

HEADER (LOCALHOST BASED ON DEFAULT SECRET KEY 'your-secret-whatever')

Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjEiLCJuYW1lIjoiSmF2aWVyIEF2aWxlcyIsImVtYWlsIjoiYXZpbGVzbG9wZXouamF2aWVyQGdtYWlsLmNvbSJ9.rgOobROftUYSWphkdNfxoN2cgKiqNXd4Km4oz6Ex4ng

• Node - Koa - Typescript Project
  • Pre-reqs
  • Features:
  • Included middleware:
• Getting Started
  • Docker (optional)
  • Setting up the Database - ORM
  • Entities validation
  • Environment variables
  • Getting TypeScript
  • Project Structure
  • Configuring TypeScript compilation
  • Running the build
• CI: Github Actions
• ESLint
  • ESLint rules
  • Running ESLint
• Register cron jobs
• Integrations and load tests
• Logging
• Authentication - Security
  • CORS
  • Helmet
• Dependencies
  • dependencies
  • devDependencies
  • Changelog
    • 1.7.1
    • 1.7.0
    • 1.6.1
    • 1.6.0
    • 1.5.0
    • 1.4.2
    • 1.4.1
    • 1.4.0
    • 1.3.0
    • 1.2.0
    • 1.1.0

Pre-reqs

To build and run this app locally you will need:

• Install Node.js

Features:

• Nodemon - server auto-restarts when code changes
• Koa v2
• TypeORM (SQL DB) with basic CRUD included
• Swagger decorator (auto generated swagger docs)
• Class-validator - Decorator based entities validation
• Docker-compose ready to go
• Postman (newman) integration tests
• Locust load tests
• Jest unit tests
• Github actions - CI for building and testing the project
• Cron jobs prepared

Included middleware:

• @koa/router
• koa-bodyparser
• Winston Logger
• JWT auth koa-jwt
• Helmet (security headers)
• CORS

Getting Started

• Clone the repository

git clone --depth=1 https://github.com/javieraviles/node-typescript-koa-rest.git <project_name>

• Install dependencies

cd <project_name>
npm install

• Run the project directly in TS

npm run watch-server

• Build and run the project in JS

npm run build
npm run start

• Run integration or load tests

npm run test:integration:local (newman needed)
npm run test:load (locust needed)

• Run unit tests

npm run test

• Run unit tests with coverage

npm run test:coverage

• Run unit tests on Jest watch mode

npm run test:watch

Docker (optional)

A docker-compose file has been added to the project with a postgreSQL (already setting user, pass and dbname as the ORM config is expecting) and an ADMINER image (easy web db client).

It is as easy as go to the project folder and execute the command 'docker-compose up' once you have Docker installed, and both the postgreSQL server and the Adminer client will be running in ports 5432 and 8080 respectively with all the config you need to start playing around.

If you use Docker natively, the host for the server which you will need to include in the ORM configuration file will be localhost, but if you were to run Docker in older Windows versions, you will be using Boot2Docker and probably your virtual machine will use your ip 192.168.99.100 as network adapter (if not, command docker-machine ip will tell you). This mean your database host will be the aforementioned ip and in case you want to access the web db client you will also need to go to http://192.168.99.100/8080

Setting up the Database - ORM

This API is prepared to work with an SQL database, using TypeORM. In this case we are using postgreSQL, and that is why in the package.json 'pg' has been included. If you where to use a different SQL database remember to install the correspondent driver.

The ORM configuration and connection to the database can be specified in the file 'ormconfig.json'. Here is directly in the connection to the database in 'server.ts' file because a environment variable containing databaseUrl is being used to set the connection data. This is prepared for Heroku, which provides a postgres-string-connection as env variable. In local is being mocked with the docker local postgres as can be seen in ".example.env"

It is importante to notice that, when serving the project directly with *.ts files using ts-node,the configuration for the ORM should specify the *.ts files path, but once the project is built (transpiled) and run as plain js, it will be needed to change it accordingly to find the built js files:

"entities": [
      "dist/entity/**/*.js"
   ],
   "migrations": [
      "dist/migration/**/*.js"
   ],
   "subscribers": [
      "dist/subscriber/**/*.js"
   ]

**NOTE: this is now automatically handled by the NODE_ENV variable too.

Notice that if NODE_ENV is set to development, the ORM config won't be using SSL to connect to the DB. Otherwise it will.

And because Heroku uses self-signed certificates, this bit has been added, please take it out if connecting to a local DB without SSL.

createConnection({
    ...
    extra: {
        ssl: {
            rejectUnauthorized: false // Heroku uses self signed certificates
        }
    }
 })

You can find an implemented CRUD of the entity user in the correspondent controller controller/user.ts and its routes in routes.ts file.

Entities validation

This project uses the library class-validator, a decorator-based entity validation, which is used directly in the entities files as follows:

export class User {
    @Length(10, 100) // length of string email must be between 10 and 100 characters
    @IsEmail() // the string must comply with an standard email format
    @IsNotEmpty() // the string can't be empty
    email: string;
}

Once the decorators have been set in the entity, you can validate from anywhere as follows:

const user = new User();
user.email = "avileslopez.javier@gmail"; // should not pass, needs the ending .com to be a valid email

validate(user).then(errors => { // errors is an array of validation errors
    if (errors.length > 0) {
        console.log("validation failed. errors: ", errors); // code will get here, printing an "IsEmail" error
    } else {
        console.log("validation succeed");
    }
});

For further documentation regarding validations see class-validator docs.

Environment variables

Create a .env file (or just rename the .example.env) containing all the env variables you want to set, dotenv library will take care of setting them. This project is using three variables at the moment:

• PORT -> port where the server will be started on, Heroku will set this env variable automatically
• NODE_ENV -> environment, development value will set the logger as debug level, also important for CI. In addition will determine if the ORM connects to the DB through SSL or not.
• JWT_SECRET -> secret value, JWT tokens should be signed with this value
• DATABASE_URL -> DB connection data in connection-string format.

Getting TypeScript

TypeScript itself is simple to add to any project with npm.

npm install -D typescript

If you're using VS Code then you're good to go! VS Code will detect and use the TypeScript version you have installed in your node_modules folder. For other editors, make sure you have the corresponding TypeScript plugin.

Project Structure

The most obvious difference in a TypeScript + Node project is the folder structure. TypeScript (.ts) files live in your src folder and after compilation are output as JavaScript (.js) in the dist folder.

The full folder structure of this app is explained below:

Note! Make sure you have already built the app using npm run build

Configuring TypeScript compilation

TypeScript uses the file tsconfig.json to adjust project compile options. Let's dissect this project's tsconfig.json, starting with the compilerOptions which details how your project is compiled.

    "compilerOptions": {
        "module": "commonjs",
        "target": "es2017",
        "lib": ["es6"],
        "noImplicitAny": true,
        "strictPropertyInitialization": false,
        "moduleResolution": "node",
        "sourceMap": true,
        "outDir": "dist",
        "baseUrl": ".",
        "experimentalDecorators": true,
        "emitDecoratorMetadata": true,  
        }
    },

The rest of the file define the TypeScript project context. The project context is basically a set of options that determine which files are compiled when the compiler is invoked with a specific tsconfig.json. In this case, we use the following to define our project context:

    "include": [
        "src/**/*"
    ]

include takes an array of glob patterns of files to include in the compilation. This project is fairly simple and all of our .ts files are under the src folder. For more complex setups, you can include an exclude array of glob patterns that removes specific files from the set defined with include. There is also a files option which takes an array of individual file names which overrides both include and exclude.

Running the build

All the different build steps are orchestrated via npm scripts. Npm scripts basically allow us to call (and chain) terminal commands via npm. This is nice because most JavaScript tools have easy to use command line utilities allowing us to not need grunt or gulp to manage our builds. If you open package.json, you will see a scripts section with all the different scripts you can call. To call a script, simply run npm run <script-name> from the command line. You'll notice that npm scripts can call each other which makes it easy to compose complex builds out of simple individual build scripts. Below is a list of all the scripts this template has available:

CI: Github Actions

Using Github Actions a pipeline is deploying the application in Heroku and running tests against it, checking the application is healthy deployed. The pipeline can be found at /.github/workflows/test.yml. This performs the following:

• Build the project
  • Install Node
  • Install dependencies
  • Build the project (transpile to JS)
  • Run unit tests
• Deploy to Heroku
  • Install Docker cli
  • Build the application container
  • Install Heroku cli
  • Login into Heroku
  • Push Docker image to Heroku
  • Trigger release in Heroku
• Run integration tests
  • Install Node
  • Install Newman
  • Run Postman collection using Newman against deployed app in Heroku
• Run load tests
  • Install Python
  • Install Locust
  • Run Locust load tests against deployed app in Heroku

ESLint

Since TSLint is deprecated now, ESLint feels like the way to go as also supports typescript. ESLint is a static code analysis tool for identifying problematic patterns found in JavaScript/typescript code.

ESLint rules

Like most linters, ESLint has a wide set of configurable rules as well as support for custom rule sets. All rules are configured through .eslintrc. In this project, we are using a fairly basic set of rules with no additional custom rules.

Running ESLint

Like the rest of our build steps, we use npm scripts to invoke ESLint. To run ESLint you can call the main build script or just the ESLint task.

npm run build   // runs full build including ESLint format check
npm run lint    // runs ESLint check + fix

Notice that ESLint is not a part of the main watch task. It can be annoying for ESLint to clutter the output window while in the middle of writing a function, so I elected to only run it only during the full build. If you are interested in seeing ESLint feedback as soon as possible, I strongly recommend the ESLint extension in VS Code.

Register cron jobs

Cron dependency has been added to the project together with types. A cron.ts file has been created where a cron job is created using a cron expression configured in config.ts file.

import { CronJob } from 'cron';
import { config } from './config';

const cron = new CronJob(config.cronJobExpression, () => {
    console.log('Executing cron job once every hour');
});

export { cron };

From the server.ts, the cron job gets started:

import { cron } from './cron';
// Register cron job to do any action needed
cron.start();

Integrations and load tests

Integrations tests are a Postman collection with assertions, which gets executed using Newman from the CI (Github Actions). It can be found at /integrationtests/node-koa-typescript.postman_collection.json; it can be opened in Postman and get modified very easily. Feel free to install Newman in your local environment and trigger npm run test:integration:local command which will use local environment file (instead of heroku dev one) to trigger your postman collection faster than using postman.

Load tests are a locust file with assertions, which gets executed from the CI (Github Actions). It can be found at /loadtests/locustfile.py; It is written in python and can be executed locally against any host once python and locust are installed on your dev machine.

**NOTE: at the end of load tests, an endpoint to remove all created test users is called.

Logging

Winston is designed to be a simple and universal logging library with support for multiple transports.

A "logger" middleware passing a winstonInstance has been created. Current configuration of the logger can be found in the file "logger.ts". It will log 'error' level to an error.log file and 'debug' or 'info' level (depending on NODE_ENV environment variable, debug if == development) to the console.

// Logger middleware -> use winston as logger (logger.ts with config)
app.use(logger(winston));

Authentication - Security

The idea is to keep the API as clean as possible, therefore the auth will be done from the client using an auth provider such as Auth0. The client making requests to the API should include the JWT in the Authorization header as "Authorization: Bearer <jwt_token>". HS256 will be used as the secret will be known by both your api and your client and will be used to sign the token, so make sure you keep it hidden.

As can be found in the server.ts file, a JWT middleware has been added, passing the secret from an environment variable. The middleware will validate that every request to the routes below, MUST include a valid JWT signed with the same secret. The middleware will set automatically the payload information in ctx.state.user.

// JWT middleware -> below this line, routes are only reached if JWT token is valid, secret as env variable
app.use(jwt({ secret: config.jwtSecret }));

Go to the website https://jwt.io/ to create JWT tokens for testing/debugging purposes. Select algorithm HS256 and include the generated token in the Authorization header to pass through the jwt middleware.

Custom 401 handling -> if you don't want to expose koa-jwt errors to users:

app.use(function(ctx, next){
  return next().catch((err) => {
    if (401 == err.status) {
      ctx.status = 401;
      ctx.body = 'Protected resource, use Authorization header to get access\n';
    } else {
      throw err;
    }
  });
});

If you want to authenticate from the API, and you fancy the idea of an auth provider like Auth0, have a look at jsonwebtoken — JSON Web Token signing and verification

CORS

This boilerplate uses @koa/cors, a simple CORS middleware for koa. If you are not sure what this is about, click here.

// Enable CORS with default options
app.use(cors());

Have a look at Official @koa/cors docs in case you want to specify 'origin' or 'allowMethods' properties.

Helmet

This boilerplate uses koa-helmet, a wrapper for helmet to work with koa. It provides important security headers to make your app more secure by default.

Usage is the same as helmet. Helmet offers 11 security middleware functions (clickjacking, DNS prefetching, Security Policy...), everything is set by default here.

// Enable helmet with default options
app.use(helmet());

Have a look at Official koa-helmet docs in case you want to customize which security middlewares are enabled.

Dependencies

Dependencies are managed through package.json. In that file you'll find two sections:

dependencies

devDependencies

To install or update these dependencies you can use npm install or npm update.

Changelog

1.8.0

• Unit tests included using Jest (Thanks to @rafapaezbas)
• Upgrade all dependencies
• Upgrade to Node 14

1.7.1

• Upgrading Locust + fixing load tests
• Improving Logger

1.7.0

• Migrating TSLint (deprecated already) to ESLint
• Node version upgraded from 10.x.x to 12.0.0 (LTS)
• Now CI installs from package-lock.json using npm ci (Beyond guaranteeing you that you'll only get what is in your lock-file it's also much faster (2x-10x!) than npm install when you don't start with a node_modules).
• included integraton test using Newman for local env too
• koa-router deprecated, using new fork from koa team @koa/router
• Dependencies updated, some @types removed as more and more libraries include their own types now!
• Typescript to latest

1.6.1

• Fixing CI
• Improving integration tests robustness

1.6.0

• CI migrated from Travis to Github actions
• cron dependency -> register cron jobs
• Node app dockerized -> now is directly pushed as a docker image to Heroku from CI, not using any webhook
• Added postman integration tests, executed from Github actions CI using Newman
• Added locust load tests, executed from Github actions CI
• PRs merged: 47, 48 and 49. Thanks to everybody!

1.5.0

• koa-swagger-decorator -> generate swagger docs with decorators in the endpoints
• Split routes into protected and unprotected. Hello world + swagger docs are not proteted by jwt
• some dependencies have been updated

1.4.2

• Fix -> npm run watch-server is now working properly live-reloading changes in the code Issue 39.
• Fix -> Logging levels were not correctly mapped. Thanks to @atamano for the PR Pull Request 35
• Some code leftovers removed

1.4.1

• Fix -> After updating winston to 3.0.0, it was throwing an error when logging errors into file
• Fix -> Config in config.ts wasn't implementing IConfig interface

鲜花

握手

雷人

路过

鸡蛋

该文章已有0人参与评论

请发表评论

评论

全部评论

专题导读

More+

10-27 六六分期app的软件客服如何联系？(六六分期
11-06 可心卡盟:win10系统火狐flash插件崩溃怎么
11-06 亲亲特价:怎么删除回收站图标
11-06 济南大学虚拟社区:鲁大师节能降温的具体办
11-06 xlueops.exe:无线网络安装向导
11-06 女斗合众国:win7系统cf与主机连接不稳定怎
11-06 0xc000022-[cf烟雾头]cf怎么调烟雾头
11-06 qizideyouhuo:应用程序无法正常启动0xc0000
11-06 ipz-185:win7系统vcf文件怎么打开
11-06 傻哥蹦迪:win10系统s4怎么打开usb调试
11-06 八神浩树gtaste:回收站清空了怎么恢复
11-06 妖尾之黑色守护:win10系统电脑没有1440x900
11-06 校园至尊魔王小说:win7系统浏览网页时字体
11-06 女斗合众国:win10系统访问共享文件夹提示请
11-06 tokyo hot n0654:恢复win7系统默认字体一招
11-06 雨酷仙境:设置win7系统转移临时文件夹腾出
11-06 阿穆纳伊之杖:win7系统开始菜单在右边还原
11-06 tunespotting:win10系统火狐flash插件总是
11-06 甘尔葛分析师：计谋网站seo关键词暴涨有什
11-06 蔡贵霖: 计谋网站seo关键词暴涨有什么秘密
11-06 博益网首页:ao3网页版进入不了解决方法
11-06 漏斗子专栏: 网站数据分析小白易懂精华篇
11-06 见证双虹怎么做:win7系统开启telnet命令的
11-06 颾狐蝶蜋:系统资源不足无法完成请求的服务
11-06 国光中学校歌:提交网站到alexa查询详细步骤
11-06 西安有情天:静态网页和动态网页的区别
11-06 红木雅尚斋:外部链接构造对网站的好处
11-06 前官礼遇：防止域名劫持–增强域安全性的10
11-06 密传二转答案: 中文分词算法有哪些
11-06 金泉家园邮编:百度快照劫持的表现及应对方

上一篇：

17koa/koa2-demo: express风格的最新的Koa 2项目的示例，已集成到koa-generator里（执 ...发布时间：2022-06-24

下一篇：

bayi-lzp/koa-template: koa-template发布时间：2022-06-24

热门推荐

More+

• 

  ctf0/Laravel-Media-Manager: A &quot;Vuej

• 

  bradtraversy/iweather: Ionic 3 mobile we

• 

  joaomh/curso-de-matlab

• 

  断牙刷新位置时间（断牙属性及刷新位置介绍

• 

  rugk/mastodon-simplified-federation: Sim

热门话题

More+

2022-11-06
剪的笔顺,诠释剪的笔画,认识剪的部首

六六分期app的软件客服如何联系？(六六分期
2023-10-27

florent37/ViewAnimator: A fluent Android
2022-08-15

florent37/Shrine-MaterialDesign2: implem
2022-08-17

CVE-2020-36276
2022-09-23

SimpleSoftwareIO/simple-sms: Send and re
2022-08-13

阅读排行榜

1 六六分期app的软件客服如何联系？(六六分期

六六分期app的软件客服如何联系？不知道吗？加qq群【895510560】即可！标题：六六分期
阅读：18314|2023-10-27
2 可心卡盟:win10系统火狐flash插件崩溃怎么

今天小编告诉大家如何处理win10系统火狐flash插件总是崩溃的问题，可能很多用户都不知
阅读：9694|2022-11-06
3 亲亲特价:怎么删除回收站图标

今天小编告诉大家如何对win10系统删除桌面回收站图标进行设置，可能很多用户都不知道
阅读：8191|2022-11-06
4 济南大学虚拟社区:鲁大师节能降温的具体办

今天小编告诉大家如何对win10系统电脑设置节能降温的设置方法，想必大家都遇到过需要
阅读：8557|2022-11-06
5 xlueops.exe:无线网络安装向导

我们在使用xp系统的过程中,经常需要对xp系统无线网络安装向导设置进行设置，可能很多
阅读：8467|2022-11-06
6 女斗合众国:win7系统cf与主机连接不稳定怎

今天小编告诉大家如何处理win7系统玩cf老是与主机连接不稳定的问题，可能很多用户都不
阅读：9408|2022-11-06
7 0xc000022-[cf烟雾头]cf怎么调烟雾头

电脑对日常生活的重要性小编就不多说了，可是一旦碰到win7系统设置cf烟雾头的问题，很
阅读：8441|2022-11-06
8 qizideyouhuo:应用程序无法正常启动0xc0000

我们在日常使用电脑的时候，有的小伙伴们可能在打开应用的时候会遇见提示应用程序无法
阅读：7873|2022-11-06
9 ipz-185:win7系统vcf文件怎么打开

今天小编告诉大家如何对win7系统打开vcf文件进行设置，可能很多用户都不知道怎么对win
阅读：8425|2022-11-06
10 傻哥蹦迪:win10系统s4怎么打开usb调试

今天小编告诉大家如何对win10系统s4开启USB调试模式进行设置，可能很多用户都不知道怎
阅读：7402|2022-11-06

• 关于我们

  创业团队 加入我们 媒体报道 合作伙伴 公益事业

• 产品与服务

  寻求合作 项目投资 干货视频 经理人培训 招聘代理

• 解决方案

  一站式 制造业 教育科研 行业案例

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服（服务时间 9:00～18:00）

在线QQ客服

地址：深圳市南山区西丽大学城创智工业园

电邮：jeky_zhao#qq.com

移动电话：139-2527-9053

Powered by 互联科技 X3.4© 2001-2213 极客世界.|Sitemap

返回顶部