Wavi Books · Python & Tự động hóa

FastAPI là gì? Hướng dẫn xây REST API bằng Python cho người mới

Nguyễn Minh Trí · Biên tập chuyên môn Wavi Books

FastAPI là gì, cách tạo REST API bằng Python, Pydantic, Uvicorn, validation và lộ trình xây backend thực tế cho người mới.

## FastAPI là gì

FastAPI là web framework Python hiện đại để xây API, tận dụng type hint để validation dữ liệu và tự sinh tài liệu OpenAPI. Framework phù hợp cho backend, dịch vụ dữ liệu và lớp API của ứng dụng AI.

Điểm mạnh của FastAPI là cú pháp rõ, hỗ trợ async và tài liệu tương tác. Tuy nhiên, một API chạy được chưa đồng nghĩa với hệ thống sẵn sàng vận hành; developer vẫn cần hiểu HTTP, database, bảo mật và kiểm thử.

## Những khái niệm cốt lõi cần nắm

- Route và HTTP method mô tả tài nguyên.

- Pydantic kiểm tra request và response.

- Dependency injection quản lý thành phần dùng chung.

- Uvicorn chạy ứng dụng theo chuẩn ASGI.

## Lộ trình thực hành từng bước

- Bước 1: Tạo CRUD API nhỏ với schema rõ ràng.

- Bước 2: Kết nối database và viết test cho endpoint.

- Bước 3: Thêm authentication, logging, Docker và triển khai thử.

## Những sai lầm thường gặp

- Dùng async nhưng gọi thư viện blocking.

- Trả lỗi không nhất quán.

- Đưa khóa bí mật trực tiếp vào mã nguồn.

## Góc nhìn dành cho người học và developer Việt Nam

Người học Python tại Việt Nam có thể dùng FastAPI để làm portfolio backend hoặc bọc mô hình AI thành dịch vụ, nhưng nên công khai tài liệu API và test thay vì chỉ quay video demo.

## Nên học tiếp như thế nào?

Sau khi nắm phần cốt lõi, bạn nên tự xây một dự án nhỏ, ghi lại giả định, tiêu chí đánh giá và giới hạn của giải pháp. Các sách liên quan được Wavi Books gợi ý trong bài giúp bạn đào sâu kiến thức theo lộ trình có hệ thống thay vì chỉ ghép các hướng dẫn rời rạc.

## FastAPI xử lý một request như thế nào?

Khi client gửi request, ASGI server như Uvicorn nhận kết nối rồi chuyển scope, receive và send cho ứng dụng. FastAPI tìm route, giải dependency, đọc path/query/header/body, dùng Pydantic validation, chạy handler và serialize response. Hiểu luồng này giúp bạn biết lỗi 422 xuất hiện ở validation, lỗi 500 ở logic hay timeout ở dependency bên ngoài.

Type hint trong FastAPI không chỉ để IDE gợi ý. Nó là hợp đồng dữ liệu cho validation, OpenAPI và tài liệu. Tuy nhiên schema API không nên dùng trực tiếp model ORM; tách request/response schema giúp tránh lộ trường nội bộ và cho phép API tiến hóa độc lập với database.

## Xây API có cấu trúc thay vì dồn vào một file

Một dự án vừa nên chia router, schema, service, repository, model, config và test. Router xử lý giao thức HTTP; service chứa luật nghiệp vụ; repository làm việc với dữ liệu. Không cần áp dụng kiến trúc nặng cho demo nhỏ, nhưng phải giữ logic nghiệp vụ ra khỏi route để test dễ hơn.

```python from fastapi import APIRouter, Depends, HTTPException, status router = APIRouter(prefix="/books", tags=["books"]) @router.get("/{book_id}", response_model=BookResponse) async def get_book(book_id: int, service: BookService = Depends(get_service)): book = await service.find_by_id(book_id) if book is None: raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Book not found") return book ```

Handler trên ngắn vì việc tìm sách nằm trong service. Khi đổi database hoặc thêm cache, hợp đồng HTTP ít bị ảnh hưởng. Response model là lớp bảo vệ để chỉ trả trường được phép.

## Async: nhanh hơn khi nào, chậm hơn khi nào?

Async hữu ích khi request chờ database, HTTP hoặc file I/O có thư viện bất đồng bộ. Nó không làm tác vụ CPU-bound như xử lý ảnh hay inference nặng nhanh hơn. Nếu gọi thư viện blocking trong async handler, event loop vẫn bị chặn. Tác vụ CPU nặng nên chuyển sang worker, process pool hoặc dịch vụ chuyên biệt.

Đừng dùng async chỉ vì framework hỗ trợ. Hãy đo concurrency, p95 latency và số connection. Database pool quá nhỏ tạo hàng đợi; pool quá lớn có thể làm database quá tải. Tối ưu một tầng mà bỏ qua giới hạn tầng sau thường không cải thiện hệ thống.

## Authentication và phân quyền

JWT chỉ là định dạng token, không tự tạo bảo mật. Cần kiểm tra chữ ký, issuer, audience, expiry và chiến lược revoke/refresh. Authentication trả lời người dùng là ai; authorization trả lời họ được làm gì trên tài nguyên nào. Phân quyền nên nằm trong dependency hoặc service, không rải điều kiện tùy ý ở nhiều route.

## Kiểm thử theo ba lớp

- Unit test cho service với repository giả.

- Integration test cho API và database thử nghiệm.

- Contract test kiểm tra schema, status code và tương thích client.

Test cần bao phủ dữ liệu sai, không có quyền, resource không tồn tại, xung đột và timeout. Chỉ test happy path tạo cảm giác an toàn giả.

## Checklist production

- Cấu hình qua environment và secret manager, không ghi khóa vào code.

- Có request ID, structured log, metric, trace và endpoint health/readiness.

- Đặt timeout cho HTTP, database; retry có backoff và chỉ dùng khi thao tác an toàn.

- Giới hạn body, rate limit, CORS và security header phù hợp.

- Chạy migration có chiến lược rollback và kiểm thử tương thích schema.

- Dùng nhiều worker theo tải và benchmark trước khi chọn con số.

## Bài tập nâng cấp

Xây API quản lý thư viện có đăng nhập, phân quyền admin/user, tìm kiếm, pagination và lịch sử mượn. Viết test cho transaction mượn sách, thêm Redis cache cho chi tiết sách, chạy job nền gửi nhắc hạn và triển khai bằng Docker. Đây là dự án đủ rộng để thể hiện backend thay vì chỉ CRUD.