Nhảy đến nội dung chính

Luồng xử lý API Backend (API Processing Flow)

1.1. Mục tiêu chương

Mô tả luồng xử lý chuẩn của một API backend từ khi nhận request đến khi deploy production nhằm:

  • Thống nhất cách xây dựng API giữa các team

  • Đảm bảo tuân thủ đầy đủ các quy định kiến trúc

  • Dễ trace lỗi và audit

  • Liên kết các chuẩn đã quy định ở các chương trước

1.2. Phạm vi áp dụng

Áp dụng cho:

  • Tất cả REST API trong modules/**

  • Core Team và Partner Team

  • Tất cả service Spring Boot

1.3. Tổng quan luồng xử lý API

Luồng chuẩn:


Client Request ↓ Security / Auth ↓ Controller ↓ DTO Validate ↓ Service Logic ↓ Repository / DB ↓ Response Mapping ↓ Logging & Audit ↓ Return Response

1.4. Các bước xử lý chi tiết

Bước 1. Client gọi API

Ví dụ:

POST /api/v1/users

Payload:

{ "username": "test", "password": "123456" }

Quy định liên quan:

👉 Chương 7 — API Design & Response Standard

Bước 2. Security / Authentication

Hệ thống kiểm tra:

  • JWT / SSO token

  • Permission

  • Role

Nếu fail:

401 Unauthorized 403 Forbidden

Quy định liên quan:

👉 Chương 8 — Cơ chế xác thực & SSO (WSO2)

Bước 3. Controller nhận request


@PostMapping public ApiResponse<UserResponse> create( @Valid @RequestBody UserCreateRequest request) { return ApiResponse.ok(userService.create(request)); }

Quy định:

  • NamingName Controller

  • Không chứa business logic

👉 Chương 3 — Coding Convention
👉 Chương 7 — API Design

Bước 4. DTO Validation

DTO:

public class UserCreateRequest { @NotBlank @Size(max = 100) private String username; @NotBlank private String password; }

Spring tự validate trước khi vào service.

Nếu lỗi:

400 Bad Request

Response chuẩn:


{ "code": "VALIDATION_ERROR", "message": "username is required" }

Quy định:

👉 Chương 3 — Coding Convention (Validation)
👉 Chương 7 — Response Standard

Bước 5. Service xử lý logic


public UserResponse create(UserCreateRequest req) { log.info("Create user {}", req.getUsername()); UserEntity e = mapper.toEntity(req); repo.save(e); return mapper.toResponse(e); }

Cấu trúc chuẩn 1 hàm service:

validate business ↓ main logic ↓ repository ↓ mapping ↓ return

Quy định:

👉 Chương 3 — Coding Convention
👉 Chương 4 — Entity & Database

Bước 6. RepositoryRepiository & Database


userRepository.save(entity);

Nếu thay đổi schema:

  • update entity

  • migration script

Quy định:

👉 Chương 4 — Thay đổi Entity & DB
👉 Chương 5 — Schema & Migration

Bước 7. Mapping Response


return UserResponse.builder() .id(e.getId()) .username(e.getUsername()) .build();

Response chuẩn:


{ "code": "SUCCESS", "data": { "id": 1, "username": "test" } }

Quy định:

👉 Chương 7 — Response Standard

Bước 8. Logging & Audit

Trong service:


log.info("User created id={}", e.getId());

Nếu nghiệp vụ quan trọng:

  • ghi audit_log

Quy định:

👉 Chương 3 — Logging
👉 Chương 6 — Audit Log

Bước 9. Exception Handling

Ví dụ:


if (exists) { throw new BusinessException("USER_EXISTS"); }

Global handler:


@ExceptionHandler(BusinessException.class)

Response:


{ "code": "USER_EXISTS", "message": "User already exists" }

Quy định:

👉 Chương 7 — Response & Error

1.5. Luồng phát triển & release API

Sau khi code xong:


Dev → Commit → PR → Review → Merge → CI Build → Deploy

Bước 10. Commit & PR

Quy định:

👉 Chương 9 — Git Workflow & Pull Request

Bước 11. Checklist trước merge

Quy định:

👉 Chương 10 — Checklist merge

Bước 12. Deploy & Update DB

Nếu có migration:

  • chạy script

  • deploy service

Quy định:

👉 Chương 5 — Migration
👉 Chương 12 — Connect DB

1.6. Sơ đồ tổng thể API lifecycle


Request ↓ Auth (Ch8) ↓ Controller (Ch3,7) ↓ DTO Validate (Ch3) ↓ Service Logic (Ch3) ↓ Entity/DB (Ch4,5) ↓ Mapping (Ch7) ↓ Logging/Audit (Ch3,6) ↓ Response (Ch7) ↓ Git/PR (Ch9,10) ↓ Deploy (Ch5,12)
Lên đầu trang