Spaces:
Sleeping
Sleeping
File size: 21,471 Bytes
b8e6260 42e30c2 b8e6260 42e30c2 b8e6260 42e30c2 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 | # Nodejs JSON API Server
[](https://nodejs.org/)
[](https://nodejs.org/)
[](https://nodejs.org/)
[](https://github.com/dangkhoa2016/NodeJs-JSON-API-Server/actions/workflows/test.yml)
[](LICENSE)
> 🌐 Language / Ngôn ngữ: [English](README.md) | **Tiếng Việt**
Một REST API tương thích JSONPlaceholder, được xây dựng chủ yếu bằng **Node.js built-ins** — dependency runtime duy nhất là `argon2` dùng để băm mật khẩu admin. Dùng `node:sqlite` để lưu trữ và một Redis client tự xây dựng trên giao thức RESP qua TCP sockets.
## Điểm nổi bật
- **Zero-framework, dependency tối thiểu** — Chỉ **1 dependency production** (`argon2`). HTTP, SQLite, networking — tất cả đều dùng built-ins của Node.js. Không Express, không ORM, không Redis driver.
- **Redis client tự xây dựng** — Một Redis client hoàn chỉnh triển khai **giao thức RESP** qua TCP sockets. Hỗ trợ `AUTH`, `SELECT`, `EVAL` (Lua script), chuỗi kết nối URL, và tự động kết nối lại — tất cả trong ~200 dòng.
- **100% kiểm thử** — **250 bài kiểm thử trên 14 file** đạt 100% ở statements, branches, functions và lines. Kiểm thử tích hợp chạy với HTTP server thật + SQLite; kiểm thử đơn vị dùng dependency injection và CJS cache mocking.
- **Giới hạn tốc độ đa tầng** — Ba tầng fallback: Redis (Lua nguyên tử) → in-memory (LRU, 10k mục) → cho phép tất cả. Tích hợp circuit breaker (3 lỗi → mở 30s), trích xuất IP proxy dựa trên CIDR, và thời gian chặn tăng dần (5 ph → 20 ph → 1 giờ).
- **Docker tối ưu cho production** — Multi-stage build, **user không phải root**, tự động thiết lập DB khi khởi động, file `.env` bị loại trừ. Dotenv bị bỏ qua trong production — mọi cấu hình đều qua biến môi trường.
- **Cấu hình runtime** — Cập nhật cài đặt rate-limit và Redis qua admin API **mà không cần khởi động lại**. Thay đổi có hiệu lực ngay lập tức qua ghi đè trong bộ nhớ.
- **Bảo mật Argon2** — Mật khẩu admin được băm bằng argon2, kết quả được lưu cache với TTL 5 giây và LRU 1k mục. Ngăn chặn SQL injection qua danh sách trắng cột và thoát LIKE. Giới hạn kích thước body ở 1 MB.
- **Dev server với file watching tích hợp** — `npm run dev` dùng cờ `--watch` gốc của Node. Không cần Nodemon, chokidar, hay bất kỳ dependency thêm nào.
- **Tài liệu song ngữ** — Đầy đủ tài liệu bằng **tiếng Anh và tiếng Việt** cho README, hướng dẫn kiểm thử và kiến trúc kỹ thuật.
## Công nghệ sử dụng
- **Node.js >= 22** — runtime với `node:sqlite`, `node:http`, `node:net` tích hợp sẵn
- **node:sqlite** — cơ sở dữ liệu SQLite (tích hợp sẵn)
- **node:http** — HTTP server (tích hợp sẵn, không dùng Express/Fastify)
- **node:net** — TCP sockets cho Redis client RESP tự xây dựng (tích hợp sẵn)
- **argon2** — băm mật khẩu an toàn cho xác thực admin (dependency runtime duy nhất)
- **RESP protocol** — Redis client tự xây dựng, triển khai Redis Serialization Protocol qua TCP
- **dotenv** — tải file môi trường (chỉ là dev dependency, bỏ qua trong production)
- **vitest** — trình chạy kiểm thử với vùng phủ V8 gốc (dev dependency)
## Yêu cầu
- **Node.js >= 22** (dùng `node:sqlite` tích hợp sẵn)
- **Redis** (không bắt buộc — giới hạn tốc độ fallback về in-memory nếu không có)
## Bắt đầu nhanh
```bash
git clone <repo-url>
cd json-api-server
npm run db:setup # tạo bảng + dữ liệu mẫu (cần chạy trước lần đầu)
npm start # khởi động server
# hoặc với file watching cho phát triển:
npm run dev
```
## Docker
### Build
```bash
docker build -t json-api-server .
```
### Chạy
```bash
docker run -d -p 3000:3000 -v ./storage:/app/storage --name json-api-server json-api-server
```
Entrypoint tự động chạy `npm run db:setup` (migrate + seed) khi container khởi động.
### Biến môi trường
```bash
docker run -d -p 3000:3000 \
-e PORT=3000 \
-e ADMIN_KEY=my-secret-key \
-e REDIS_HOST=redis \
-v ./storage:/app/storage \
--name json-api-server json-api-server
```
### Ghi chú
- Container chạy với user `app` (không phải root).
- File database được lưu trong `/app/storage` (khai báo là `VOLUME`).
- `NODE_ENV=production` được đặt mặc định — dotenv **bị bỏ qua**, do đó mọi cấu hình phải được truyền qua biến môi trường (xem bên dưới).
- File `.env` và `.env.*` bị loại trừ bởi `.dockerignore` và **không được copy** vào image.
- Entrypoint chạy `npm run db:setup` khi container khởi động.
### Cấu hình môi trường
Container chạy với `NODE_ENV=production`, khi đó `src/config/load-env.js` **bỏ qua hoàn toàn dotenv**. Kết hợp với `.dockerignore` loại trừ mọi file `.env*`, bạn **bắt buộc** phải truyền cấu hình qua biến môi trường Docker.
**Khuyến nghị**: truyền biến trực tiếp:
```bash
docker run -d -p 3000:3000 \
-e PORT=3000 \
-e ADMIN_KEY=my-secret-key \
-e REDIS_HOST=redis \
-e SEED_API_BASE_URL=https://jsonplaceholder.typicode.com \
-v ./storage:/app/storage \
--name json-api-server json-api-server
```
**Cách khác — mount file env** (chỉ hoạt động với `NODE_ENV=production-local`):
```bash
docker run -d -p 3000:3000 \
-e NODE_ENV=production-local \
-v ./.env.prod:/app/.env.prod \
-v ./storage:/app/storage \
--name json-api-server json-api-server
```
> **Lưu ý:** Node 22 có thể hiển thị cảnh báo rằng `node:sqlite` đang ở giai đoạn thử nghiệm. Điều này vô hại.
---
## Cấu hình
File môi trường được tải bởi `src/config/load-env.js` (tự động chạy qua `src/config/index.js`). Tất cả file hiện có trong chuỗi đều được tải với `override: false` — giá trị `process.env` và file trước có quyền cao hơn file sau. Biến môi trường hệ thống luôn có quyền cao nhất (ví dụ: `PORT=5000 npm start`).
`NODE_ENV` mặc định là `development` nếu không được đặt. Trong môi trường **production**, `dotenv` **hoàn toàn bị bỏ qua** — hãy đặt biến môi trường thông qua môi trường triển khai của bạn (systemd, Docker, Kubernetes, v.v.).
| NODE_ENV | dotenv | Chuỗi fallback (thử theo thứ tự) |
|---------------------|--------|-----------------------------------|
| `development` | ✅ | `.env` ← `.env.dev` ← `.env.development` |
| `production-local` | ✅ | `.env.prod` ← `.env.production` |
| `test` | ✅ | `.env.test` |
| `production` | ❌ bỏ qua | _(dùng biến môi trường hệ thống)_ |
### Biến
| Biến | Mặc định | Mô tả |
|------------------------|-------------|----------------------------------------|
| `PORT` | `3000` | Cổng server |
| `DB_PATH` | `./storage/data.db` | Đường dẫn file SQLite |
| `REDIS_URL` | _(không)_ | URL kết nối Redis (ưu tiên cao hơn). Định dạng: `redis://user:password@host:port/db` |
| `REDIS_HOST` | `127.0.0.1` | Redis host |
| `REDIS_PORT` | `6379` | Redis port |
| `REDIS_DB` | `0` | Chỉ mục database Redis |
| `REDIS_PASSWORD` | _(không)_ | Mật khẩu Redis (cho `AUTH`) |
| `RATE_LIMIT_ENABLED` | `true` | Bật/tắt giới hạn tốc độ |
| `RATE_LIMIT_MAX` | `100` | Số request tối đa trong một khoảng thời gian |
| `DEBUG_SQL` | `false` | Ghi log tất cả truy vấn SQL ra stderr (`true`/`false`) |
| `RATE_LIMIT_WINDOW_MS` | `60000` | Khoảng thời gian tính bằng mili giây (mặc định 1 phút) |
| `SEED_API_BASE_URL` | `https://jsonplaceholder.typicode.com` | URL gốc cho API dữ liệu mẫu |
| `MAX_BODY_SIZE` | `1048576` | Kích thước body request tối đa tính bằng byte (tối thiểu 1) |
| `DEFAULT_PAGE_SIZE` | `10` | Số kết quả mặc định mỗi trang cho phân trang `_page`/`_limit` |
| `ADMIN_KEY` | _(không)_ | Khóa chính để xác thực request admin API (Bearer token) |
| **Cập nhật runtime** | — | Patching `RATE_LIMIT_ENABLED`, `RATE_LIMIT_MAX`, `RATE_LIMIT_WINDOW_MS`, `REDIS_URL`, `REDIS_HOST`, `REDIS_PORT`, `REDIS_DB`, hoặc `REDIS_PASSWORD` qua admin API áp dụng thay đổi ngay lập tức — không cần khởi động lại server |
---
## API Endpoints
### Tài nguyên
| Method | Path | Mô tả |
|----------|-----------------------------|------------------------------|
| `GET` | `/api/users` | Danh sách tất cả user |
| `GET` | `/api/users/:id` | Lấy user theo ID |
| `GET` | `/api/users/:id/posts` | Bài viết của user |
| `GET` | `/api/users/:id/albums` | Album của user |
| `GET` | `/api/users/:id/todos` | Việc cần làm của user |
| `GET` | `/api/posts` | Danh sách tất cả bài viết |
| `GET` | `/api/posts/:id` | Lấy bài viết theo ID |
| `GET` | `/api/posts/:id/comments` | Bình luận của bài viết |
| `GET` | `/api/comments` | Danh sách tất cả bình luận |
| `GET` | `/api/albums` | Danh sách tất cả album |
| `GET` | `/api/albums/:id/photos` | Ảnh trong album |
| `GET` | `/api/photos` | Danh sách tất cả ảnh |
| `GET` | `/api/todos` | Danh sách tất cả việc cần làm|
| `POST` | `/api/:table` | Tạo tài nguyên mới |
| `PUT` | `/api/:table/:id` | Thay thế toàn bộ tài nguyên |
| `PATCH` | `/api/:table/:id` | Cập nhật một phần |
| `DELETE` | `/api/:table/:id` | Xóa tài nguyên |
> **Xóa tầng (cascade)**: Xóa `user` sẽ xóa `posts`, `albums`, và `todos` của họ. Xóa `post` sẽ xóa `comments` của nó. Xóa `album` sẽ xóa `photos` của nó.
### Lọc theo query string và phân trang
```bash
# Lọc bài viết theo userId
GET /api/posts?userId=1
# Lọc việc cần làm theo userId và trạng thái hoàn thành
GET /api/todos?userId=1&completed=false
# Lọc bình luận theo postId
GET /api/comments?postId=1
```
Các cột có thể lọc khác nhau theo bảng (ví dụ: `title`, `email`, `username`). Trường `completed` chấp nhận chuỗi `true`/`false`.
### Phân trang
| Tham số | Mô tả | Ví dụ |
|-----------|------------------------------------------------|------------------------------|
| `_page` | Số trang (bắt đầu từ 1), dùng với `_limit` | `?_page=1&_limit=10` |
| `_limit` | Số mục mỗi trang (mặc định: `DEFAULT_PAGE_SIZE`)| `?_page=2&_limit=5` |
| `_start` | Chỉ số bắt đầu để cắt | `?_start=10&_end=20` |
| `_end` | Chỉ số kết thúc (không bao gồm) để cắt | `?_start=0&_end=5` |
### Tìm kiếm
Tìm kiếm trên các cột văn bản bằng tham số `q`. Các cột có thể tìm kiếm khác nhau theo bảng:
| Bảng | Cột có thể tìm kiếm |
|------------|-------------------------------------------|
| `users` | `name`, `username`, `email` |
| `posts` | `title`, `body` |
| `comments` | `name`, `email`, `body` |
| `albums` | `title` |
| `photos` | `title` |
| `todos` | `title` |
```bash
# Tìm bài viết theo tiêu đề hoặc nội dung
GET /api/posts?q=first
# Kết hợp tìm kiếm với bộ lọc
GET /api/posts?q=Post&userId=1
# Tìm việc cần làm
GET /api/todos?q=groceries
```
### Sắp xếp
| Tham số | Giá trị | Mô tả |
|----------|----------------|--------------------------------------|
| `_sort` | tên cột | Cột để sắp xếp |
| `_order` | `asc` / `desc` | Hướng sắp xếp (mặc định: `asc`) |
```bash
# Sắp xếp bài viết theo tiêu đề tăng dần
GET /api/posts?_sort=title&_order=asc
# Sắp xếp bài viết theo tiêu đề giảm dần
GET /api/posts?_sort=title&_order=desc
# Kết hợp sắp xếp với phân trang
GET /api/posts?_sort=id&_order=desc&_limit=2
```
### Endpoint hệ thống
| Path | Mô tả |
|-----------------------------------|--------------------------------------|
| `GET /` | Thông tin API với các endpoint có sẵn|
| `GET /api` | Thông tin API (giống như trên) |
| `GET /health` | Trạng thái server (Redis, bảng, cấu hình giới hạn tốc độ) |
| `GET /api/health` | Giống như trên |
| `GET /api/admin/settings` | Danh sách tất cả cài đặt (yêu cầu xác thực) |
| `PATCH /api/admin/settings/:key` | Cập nhật giá trị cài đặt — thay đổi rate-limit & Redis có **hiệu lực ngay lập tức** (yêu cầu xác thực) |
| `POST /api/admin/reset-database` | Xóa bảng dữ liệu và seed lại từ JSONPlaceholder (yêu cầu xác thực) |
### Admin API
Các endpoint admin được bảo vệ bằng xác thực Bearer token sử dụng biến môi trường `ADMIN_KEY`. Giá trị cài đặt được lưu trong bảng `settings` của database.
```bash
# Danh sách tất cả cài đặt
curl http://localhost:3000/api/admin/settings \
-H "Authorization: Bearer my-secret-key"
# Cập nhật cài đặt
curl -X PATCH http://localhost:3000/api/admin/settings/NODE_ENV \
-H "Authorization: Bearer my-secret-key" \
-H "Content-Type: application/json" \
-d '{"value": "production"}'
# Đặt lại database (xóa toàn bộ dữ liệu và tải lại từ JSONPlaceholder)
curl -X POST http://localhost:3000/api/admin/reset-database \
-H "Authorization: Bearer my-secret-key" \
-H "Content-Type: application/json" \
-d '{"confirm": true}'
```
`ADMIN_KEY` được băm bằng **argon2** trước khi lưu trữ. Khi cập nhật mật khẩu qua `PATCH /api/admin/settings/ADMIN_KEY`, giá trị mới tự động được băm. Mật khẩu không bao giờ được lưu dưới dạng văn bản thuần túy.
**Cập nhật cấu hình runtime**: Khi patching cài đặt rate-limit (`RATE_LIMIT_ENABLED`, `RATE_LIMIT_MAX`, `RATE_LIMIT_WINDOW_MS`) hoặc cài đặt kết nối Redis (`REDIS_HOST`, `REDIS_PORT`, `REDIS_DB`, `REDIS_PASSWORD`, `REDIS_URL`), server áp dụng thay đổi ngay lập tức qua lớp `RuntimeConfig` — không cần khởi động lại. Thay đổi rate-limit gọi `rateLimiter.updateConfig()` để hot-swap hành vi middleware, trong khi cài đặt Redis kích hoạt kết nối lại an toàn qua `Redis.reconnect()`.
Kết quả xác minh Argon2 được **lưu cache trong bộ nhớ 5 giây** cho mỗi token, tránh băm lặp lại trên các request admin liên tiếp. Khi có lỗi, kết quả cũng được lưu cache là không hợp lệ — ngăn chặn rò rỉ thông tin qua timing hoặc thông báo lỗi.
---
## Response Headers
Mọi response đều bao gồm header CORS và giới hạn tốc độ:
```
Access-Control-Allow-Origin: *
X-Powered-By: json-api-server/1.0
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 58 ← giây cho đến khi cửa sổ reset
X-RateLimit-Store: redis ← "redis" hoặc "memory"
```
Khi vượt quá giới hạn tốc độ, response `429 Too Many Requests` được trả về:
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 0
X-RateLimit-Store: redis
Retry-After: 300
```
```json
{
"error": "Too Many Requests",
"message": "Rate limit exceeded. Max 100 requests per 60s window.",
"retryAfter": 300
}
```
---
## Ví dụ
```bash
# Danh sách user
curl http://localhost:3000/api/users
# Tạo bài viết mới
curl -X POST http://localhost:3000/api/posts \
-H "Content-Type: application/json" \
-d '{"userId": 1, "title": "Hello", "body": "World"}'
# Cập nhật một phần
curl -X PATCH http://localhost:3000/api/posts/1 \
-H "Content-Type: application/json" \
-d '{"title": "Updated title"}'
# Xóa
curl -X DELETE http://localhost:3000/api/posts/1
# Kiểm tra sức khỏe
curl http://localhost:3000/health
```
Xem [docs/TECHNICAL.vi.md](docs/TECHNICAL.vi.md) để biết kiến trúc và ghi chú triển khai chi tiết.
## Database
- **7 bảng:** `users`, `posts`, `comments`, `albums`, `photos`, `todos`, `settings`
- **Chế độ WAL** cho hiệu suất đọc đồng thời tốt hơn
- **Ràng buộc khóa ngoại** được thực thi qua `PRAGMA foreign_keys=ON`
- **Dữ liệu mẫu** được lấy từ [JSONPlaceholder](https://jsonplaceholder.typicode.com) lần chạy đầu:
- 10 users (với `address` và `company` lưu dưới dạng JSON, phân tích khi đọc)
- 100 bài viết
- 500 bình luận
- 100 album
- 5000 ảnh
- 200 việc cần làm
- 14 cài đặt (biến môi trường: `NODE_ENV`, `PORT`, `DB_PATH`, `DEBUG_SQL`, `REDIS_HOST`, `REDIS_PORT`, `REDIS_DB`, `REDIS_PASSWORD`, `REDIS_URL`, `RATE_LIMIT_ENABLED`, `RATE_LIMIT_MAX`, `RATE_LIMIT_WINDOW_MS`, `DEFAULT_PAGE_SIZE`, `ADMIN_KEY`)
### Script hỗ trợ
```bash
sqlite3 storage/data.db < manual/inspect-queries.sql
```
Script này chạy các truy vấn toàn diện để kiểm tra số lượng dòng, metadata cột, quan hệ, kiểm tra toàn vẹn và thống kê.
### Script Database
| Script | Lệnh | Mô tả |
|---------------|---------------------------|-------------------------------------------------------|
| `db:migrate` | `npm run db:migrate` | Tạo 7 bảng (dotenv được tải bởi config.js) |
| `db:seed` | `npm run db:seed` | Lấy dữ liệu mẫu từ [JSONPlaceholder](https://jsonplaceholder.typicode.com), tự động chạy migrate + seed-settings |
| `db:seed-settings` | `npm run db:seed-settings` | Seed biến môi trường vào bảng `settings` (dotenv được tải bởi config.js) |
| `db:setup` | `npm run db:setup` | Chạy `db:seed` + `db:seed-settings` (migrate + JSONPlaceholder + env settings) |
| `test` | `npm test` | Chạy kiểm thử tích hợp vitest |
| `test:coverage` | `npm run test:coverage` | Chạy kiểm thử với báo cáo vùng phủ V8 |
---
## Kiểm thử
Sử dụng **vitest** với **vùng phủ V8 gốc**. **250 bài kiểm thử trên 14 file** bao phủ toàn bộ stack — từ kiểm thử tích hợp (HTTP server thật + SQLite) đến kiểm thử đơn vị cho mọi module.
```bash
npm test # Chạy tất cả kiểm thử một lần
npm run test:watch # Chế độ watch
npm run test:coverage # Với báo cáo vùng phủ (100% trên mọi chỉ số)
```
Xem [tests/README.md](tests/README.md) để biết tài liệu đầy đủ.
## Dự án tương tự
Nếu bạn thích server này nhưng muốn có **giao diện dashboard** được xây dựng bằng **Tailwind CSS**, hãy xem:
- **GitHub:** [JSON-API-Server-With-Dashboard-UI](https://github.com/dangkhoa2016/JSON-API-Server-With-Dashboard-UI)
Dự án cung cấp cùng API tương thích JSONPlaceholder nhưng kèm giao diện web trực quan — cũng rất hay!
## Giấy phép
[MIT](LICENSE) — Bản quyền (c) 2026 Dang Khoa <i.am@dangkhoa.dev>
## Ghi công
Dự án này có sử dụng tài nguyên đồ họa từ Flaticon:
* [Sustainability stickers](https://www.flaticon.com/free-stickers/sustainability) được sáng tạo bởi [Manuel Viveros - Flaticon](https://www.flaticon.com/authors/manuel-viveros?type=sticker)
|