Xây dựng API Backend với Node.js và TypeScript: Hướng dẫn Khởi tạo Dự án Cực Nhanh và Hiện Đại

Lê Lân

14/06/2025

Hướng Dẫn Xây Dựng API Backend Với Node.js Và Express: Nhanh, Hiện Đại Và Dễ Dàng

Mở Đầu

Việc xây dựng một backend API trong Node.js, đặc biệt là với Express, có thể là một thử thách không nhỏ đối với nhiều nhà phát triển, nhất là khi phải thiết lập dự án từ đầu. Nếu bạn từng cảm thấy mệt mỏi và muốn bỏ cuộc trước khi bắt đầu tạo ra ứng dụng mạng xã hội thế hệ mới, thì bạn không đơn độc. Trên thực tế, các hướng dẫn nhanh và hiện đại để xây dựng một API Express có cấu trúc tốt đang rất thiếu hụt.

Trong bài viết này, tôi sẽ giúp bạn nắm rõ từng bước thiết lập một dự án backend API bằng Node.js với Express và TypeScript - từ khởi tạo dự án, cài đặt, cấu hình, phát triển, đến thiết lập kiểm thử và linting. Tất cả được trình bày chi tiết và dễ hiểu để bạn có thể bắt tay xây dựng sản phẩm thật nhanh chóng và hiệu quả.

1. Khởi Tạo Dự Án Với `npm init`

Bước đầu tiên để có một dự án Node.js là khởi tạo package.json , nơi quản lý các phụ thuộc và script của dự án.

npm init -y

-y giúp dùng mặc định tất cả cài đặt để bạn tiết kiệm thời gian.

package.json sẽ giúp bạn theo dõi & cài đặt các thư viện sau này.

Lưu ý: Luôn bắt đầu bằng việc khởi tạo dự án với npm init để đồng bộ quản lý các package.

2. Cài Đặt Express Và Các Thư Viện Hỗ Trợ Phát Triển

Để xây dựng một API hiện đại, ta cần dùng Express cùng nhiều thư viện hỗ trợ đặc biệt cho TypeScript và kiểm thử.

npm install express
npm install --save-dev typescript supertest nodemon jest ts-jest ts-node @types/jest @types/supertest @types/express

Thư viện	Mục đích
express	Framework HTTP chính cho server
typescript	Cho lập trình TypeScript chặt chẽ
supertest	Kiểm thử API endpoints
jest, ts-jest	Framework test và hỗ trợ TypeScript
nodemon	Tự khởi động lại server khi đổi code
ts-node	Chạy trực tiếp file TypeScript
types/*	Thêm hỗ trợ type cho thư viện liên quan

3. Cấu Hình TypeScript Cho Dự Án

Khởi tạo file cấu hình TypeScript:

npx tsc --init

Sau đó, thay nội dung trong tsconfig.json bằng:

{
  "exclude": ["./coverage", "./dist", "**/*.test.ts", "jest.config.js", "eslint.config.mjs"],
  "ts-node": {
    "transpileOnly": true,
    "files": true
  },
  "compilerOptions": {
    "target": "es2016",
    "module": "commonjs",
    "rootDir": "./src",
    "moduleResolution": "node",
    "checkJs": true,
    "outDir": "./dist",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "noImplicitAny": true,
    "skipLibCheck": true
  }
}

Chú ý: Khi mới tạo, linter có thể báo lỗi cho đến khi bạn tạo file .ts đầu tiên.

4. Tạo Ứng Dụng Express Cơ Bản

Cấu Trúc Thư Mục

src/
├── app.ts
├── app.test.ts
├── server.ts
└── routes/
    ├── user.routes.ts
    └── user.routes.test.ts

Nội Dung `src/server.ts`

import app from './app';

const PORT: number = 5050;

app.listen(PORT, (): void => {
  // eslint-disable-next-line no-console
  console.log(`Server is running on ${PORT}...`);
});

Nội Dung `src/app.ts`

import express, { Application, Request, Response } from 'express';
import { router as userRoutes } from './routes/user.routes';

const app: Application = express();

app.use('/users', userRoutes);

app.use('/', (req: Request, res: Response): void => {
  res.json({ message: "Miley, what's good?" });
});

export default app;

Nội Dung `src/routes/user.routes.ts`

import { Router, Request, Response } from 'express';

const router = Router();

router.get('/', (req: Request, res: Response): void => {
  const users = ['Nicki', 'Ariana', 'Lana', 'Miley'];
  res.status(200).send(users);
});

export { router };

<b>Điểm quan trọng:</b> Sử dụng router riêng biệt giúp mở rộng API dễ dàng, tách biệt logic rõ ràng.

5. Thiết Lập Công Cụ Kiểm Thử Với Jest Và Supertest

Khởi tạo cấu hình Jest cho TypeScript:

npx ts-jest config:init

Thay nội dung jest.config.js thành:

export const preset = 'ts-jest';
export const testEnvironment = 'node';

6. Viết Các Bài Kiểm Thử Cơ Bản

`src/app.test.ts`

import request from 'supertest';
import app from './app';

describe('Test app.ts', () => {
  test('Is alive route', async () => {
    const res = await request(app).get('/');
    expect(res.body).toEqual({ message: "Miley, what's good?" });
  });
});

`src/routes/user.routes.test.ts`

import request from 'supertest';
import app from '../app';

describe('User routes', () => {
  test('Get all users', async () => {
    const res = await request(app).get('/users');
    expect(res.body).toEqual(['Nicki', 'Ariana', 'Lana', 'Miley']);
  });
});

7. Cập Nhật Scripts Trong `package.json`

"scripts": {
  "test": "jest --coverage",
  "dev": "nodemon ./src/server.ts",
  "build": "tsc",
  "lint": "eslint src/**/*.ts",
  "lint:fix": "eslint . --ext .ts,.tsx,.js,.jsx --fix"
}

Loại bỏ "type": "module" khỏi package.json để tránh xung đột.

Sử dụng npm run test để chạy kiểm thử với báo cáo coverage chi tiết.

npm run dev khởi động server tự động restart khi có thay đổi.

8. Thiết Lập ESLint Và Prettier Cho Mã Nguồn Sạch

Cài đặt các thư viện cần thiết:

npm install -D eslint @eslint/js @types/eslint__js typescript-eslint eslint-plugin-prettier eslint-config-prettier

Tạo file cấu hình eslint.config.mjs :

import js from '@eslint/js';
import tseslint from 'typescript-eslint';
import eslintPluginPrettier from 'eslint-plugin-prettier';
import prettier from 'eslint-config-prettier';

export default [
  js.configs.recommended,
  ...tseslint.configs.recommended,
  {
    files: ['**/*.ts'],
    languageOptions: {
      parser: tseslint.parser,
      parserOptions: {
        project: './tsconfig.eslint.json',
        sourceType: 'module',
      },
    },
    plugins: {
      prettier: eslintPluginPrettier,
    },
    rules: {
      'no-unused-vars': 'error',
      'no-undef': 'off',
      'prefer-const': 'error',
      'no-console': 'warn',
      'no-debugger': 'warn',
      'prettier/prettier': [
        'error',
        {
          singleQuote: true,
          semi: true,
          trailingComma: 'all',
          printWidth: 100,
          tabWidth: 2,
        },
      ],
    },
  },
  prettier,
  {
    ignores: ['dist/**', 'node_modules/**', 'coverage/**'],
  },
];

Tạo tsconfig.eslint.json để ESLint hiểu được cấu hình TypeScript:

{
  "extends": "./tsconfig.json",
  "include": ["src/**/*.ts", "src/**/*.tsx"],
  "exclude": ["node_modules", "dist"]
}

Lợi ích: Mã nguồn được tự động format và bắt lỗi trước khi commit, đảm bảo codebase sạch và chuẩn ngay từ đầu.

Kết Luận

Bạn đã có trong tay một bộ khung backend API bằng Node.js và Express với:

TypeScript mạnh mẽ giúp lập trình an toàn và chuyên nghiệp hơn

Kiểm thử bài bản nhờ Jest và Supertest

Quy trình phát triển tiện lợi với Nodemon, ESLint và Prettier

Với những thiết lập này, bạn có thể tập trung phát triển tính năng mà không phải lo lắng về phần cài đặt và quản lý dự án phức tạp nữa. Đừng ngần ngại mở rộng, mở module mới và thử nghiệm các ý tưởng của bạn ngay!