08 thg 9, 2025·8 phút
FastAPI là gì? Hướng dẫn thực tế để xây dựng API
FastAPI là một framework Python hiện đại để xây dựng API nhanh, với gợi ý kiểu, xác thực dữ liệu và tài liệu OpenAPI tự động. Tìm hiểu những điều cơ bản và cách sử dụng.
FastAPI là một framework Python hiện đại để xây dựng API nhanh, với gợi ý kiểu, xác thực dữ liệu và tài liệu OpenAPI tự động. Tìm hiểu những điều cơ bản và cách sử dụng.
FastAPI là một framework Python để xây API web nhanh chóng, với mã rõ ràng và tài liệu tự động. Bạn viết các hàm nhỏ (gọi là “endpoint”) khai báo dữ liệu API chấp nhận và trả về, và FastAPI xử lý phần hạ tầng web—routing, xác thực và tạo phản hồi JSON.
API là một tập hợp URL cho phép một phần mềm giao tiếp với phần mềm khác.
Ví dụ, một ứng dụng thời tiết trên điện thoại có thể gọi một URL như GET /weather?city=Berlin. Server trả về dữ liệu có cấu trúc (thường là JSON), chẳng hạn nhiệt độ và dự báo. Ứng dụng điện thoại không cần truy cập trực tiếp vào cơ sở dữ liệu của server—nó chỉ gọi API và hiển thị kết quả.
FastAPI giúp bạn tạo những URL và phản hồi đó bằng Python.
Bạn không cần là chuyên gia async để bắt đầu; bạn có thể viết endpoint đơn giản và áp dụng các mẫu nâng cao khi cần.
FastAPI nhanh chóng được ưa chuộng vì nó loại bỏ nhiều ma sát thường gặp khi xây API bằng Python.
Các dự án API truyền thống thường bắt đầu với thiết lập chậm và nhiều “điện nước”:
Các tính năng chính của FastAPI nhắm trực tiếp vào những vấn đề này, nên đội ngũ dành nhiều thời gian hơn để thiết kế endpoint và ít thời gian hơn để vật lộn với boilerplate của framework.
FastAPI dựa nhiều vào Python type hints. Khi bạn khai báo một trường là int, optional, hoặc một danh sách của một kiểu nào đó, FastAPI dùng thông tin này để xác thực đầu vào và định hình đầu ra.
Điều này giảm lỗi do kiểu dữ liệu dùng không nhất quán (ví dụ: xử lý ID như chuỗi ở chỗ này và số ở chỗ khác) và khuyến khích endpoint hành xử nhất quán. Vẫn là Python, nhưng với kỳ vọng rõ ràng được thể hiện trong chữ ký hàm.
Bởi vì schema API được suy ra từ mã, FastAPI có thể sinh ra tài liệu tương tác tự động (OpenAPI + Swagger UI/ReDoc). Điều này quan trọng cho hợp tác: frontend, QA và integrator có thể khám phá endpoint, thử request và xem model chính xác mà không phải chờ một nỗ lực viết tài liệu riêng.
FastAPI không thể sửa một API thiết kế tồi. Bạn vẫn cần đặt tên tốt, versioning, xử lý lỗi và quyết định bảo mật hợp lý. Những gì nó mang lại là một con đường sạch hơn từ “ý tưởng” đến “API xác định rõ” với ít bất ngờ hơn.
FastAPI có vẻ đơn giản khi bạn hiểu một vài ý tưởng cốt lõi mà nó xây dựng trên đó. Bạn không cần nhớ mọi nội dung bên trong—chỉ cần nhận diện các phần bạn sẽ dùng hàng ngày.
Một framework là tập hợp công cụ và quy ước để xây API mà không bắt đầu từ con số 0. FastAPI cung cấp phần “điện nước” cho các tác vụ API phổ biến: định nghĩa endpoint, đọc input, trả output, xử lý lỗi và tổ chức mã thành cấu trúc dễ duy trì.
Routing là cách bạn ánh xạ một URL và phương thức HTTP tới một đoạn mã Python.
Ví dụ, bạn có thể route GET /users tới “liệt kê người dùng” và POST /users tới “tạo người dùng.” Trong FastAPI, bạn thường định nghĩa route bằng các decorator như @app.get(...) và @app.post(...), giúp dễ dàng nhìn thấy API của bạn ở cái nhìn đầu tiên.
Mỗi cuộc gọi API là một request (khách gửi) và một response (server trả về).
FastAPI giúp bạn:
/users/{id}), query string (?page=2), header và body request200, 201, 404)FastAPI chạy trên ASGI, một chuẩn hiện đại cho server web Python. Thực tế, điều này có nghĩa FastAPI được thiết kế để xử lý nhiều kết nối hiệu quả, và có thể hỗ trợ các tính năng như kết nối dài (ví dụ WebSockets) khi cần—mà bạn không phải quản lý mạng ở mức thấp.
Type hints Python (như str, int, list[Item]) không chỉ để tài liệu trong FastAPI—chúng là đầu vào quan trọng. FastAPI dùng chúng để hiểu dữ liệu bạn mong đợi, chuyển đổi giá trị đầu vào về kiểu đúng và tạo API rõ ràng hơn, dễ dự đoán hơn.
Pydantic models cho phép bạn định nghĩa hình dạng dữ liệu (các trường, kiểu, giá trị optional) ở một nơi duy nhất. FastAPI dùng các model này để xác thực JSON đầu vào, từ chối input không hợp lệ với thông báo lỗi hữu ích, và serialize output nhất quán—vì vậy API của bạn hoạt động tin cậy ngay cả khi client gửi dữ liệu lộn xộn.
Ứng dụng FastAPI được xây quanh endpoints: một đường dẫn cộng với một phương thức HTTP. Hãy nghĩ endpoint là “khách yêu cầu gì” và “khách yêu cầu bằng cách nào.” Ví dụ, client có thể GET /users để liệt kê người dùng, hoặc POST /users để tạo một người dùng.
Một path là route, và method là hành động:
GET /products → lấy dữ liệuPOST /products → gửi dữ liệu để tạo mớiPUT /products/123 → thay thế/cập nhậtDELETE /products/123 → xoáFastAPI tách dữ liệu là một phần của đường dẫn và dữ liệu là bộ lọc tùy chọn:
GET /users/42 → 42 là user ID.? và thường tùy chọn.
GET /users?limit=10&active=true → limit và active điều khiển kết quả trả về.Khi client gửi dữ liệu có cấu trúc (thường JSON), nó nằm trong request body, thường dùng với POST hoặc PUT.
Ví dụ: POST /orders với JSON như { "item_id": 3, "quantity": 2 }.
FastAPI có thể trả các object Python thuần túy (như dict), nhưng điểm mạnh là khi bạn định nghĩa response model. Model đó đóng vai trò hợp đồng: các trường nhất quán, loại dữ liệu được lọc dư thừa, và kiểu được đảm bảo. Kết quả là API sạch hơn—client biết nên mong đợi gì và bạn tránh các phản hồi “bất ngờ” phá vỡ tích hợp.
“Async” (viết tắt của asynchronous) là cách để API của bạn xử lý nhiều request hiệu quả khi nhiều thời gian bị dành cho chờ đợi.
Tưởng tượng một barista nhận order. Nếu họ phải đứng im làm cà phê và không làm gì khi máy chạy, họ sẽ phục vụ ít khách hơn. Cách tốt hơn là: khởi tạo việc pha, rồi nhận order tiếp trong lúc máy làm cà phê.
Async hoạt động như vậy. Ứng dụng FastAPI có thể bắt đầu một thao tác chờ—như gọi network hoặc database—và trong lúc chờ, nó chuyển sang xử lý request khác.
Async tỏa sáng khi API của bạn làm nhiều I/O (input/output)—những việc tốn thời gian chờ hơn là “tính toán”. Ví dụ:
Nếu endpoint thường xuyên chờ các hoạt động này, async có thể tăng throughput và giảm nguy cơ request dồn ứ khi tải cao.
Async không phải nút tăng tốc mọi thứ. Nếu endpoint chủ yếu nặng CPU—như thay đổi kích thước ảnh lớn, chạy tính toán data science, hoặc mã hóa khối lượng lớn—async sẽ không làm phép tính nhanh hơn. Trong những trường hợp đó, bạn cần chiến lược khác (worker nền, process pool, hoặc scale out).
Bạn không phải viết lại mọi thứ để dùng FastAPI. Bạn có thể viết hàm route đồng bộ thông thường và FastAPI vẫn chạy ổn. Nhiều dự án kết hợp cả hai: giữ endpoint đơn giản là sync, và dùng async def ở nơi rõ ràng cần (thường quanh các lần gọi database hoặc HTTP ngoài).
Xác thực là điểm kiểm tra giữa thế giới bên ngoài và mã của bạn. Khi API nhận input (JSON body, query params, path params), bạn muốn chắc chắn dữ liệu đầy đủ, kiểu đúng và trong giới hạn hợp lý—trước khi ghi vào database, gọi dịch vụ khác hoặc kích hoạt logic nghiệp vụ.
FastAPI dựa vào Pydantic cho việc này. Bạn mô tả “dữ liệu tốt” trông như thế nào một lần, và FastAPI tự động:
Nếu client gửi dạng dữ liệu sai, FastAPI trả 422 Unprocessable Entity và payload lỗi có cấu trúc chỉ ra trường và lý do chính xác. Điều đó giúp developer bên client sửa request nhanh hơn, không phải đoán mò.
Đây là một model nhỏ thể hiện trường bắt buộc, kiểu, ràng buộc min/max và định dạng:
from pydantic import BaseModel, EmailStr, Field
class UserCreate(BaseModel):
email: EmailStr
age: int = Field(ge=13, le=120)
username: str = Field(min_length=3, max_length=20)
email phải có.age phải là số nguyên.age nằm trong 13–120.EmailStr đảm bảo email hợp lệ.Cùng các model đó có thể định hình đầu ra, nên phản hồi API của bạn không vô tình lộ trường nội bộ. Bạn trả object Python; FastAPI (qua Pydantic) chuyển chúng thành JSON với tên trường và kiểu đúng.
Một trong những tính năng thực tế nhất của FastAPI là nó sinh ra tài liệu API cho bạn tự động—dựa trên mã bạn đã viết.
OpenAPI là chuẩn mô tả API ở dạng có cấu trúc (thường JSON). Hãy coi nó là “hợp đồng” ghi rõ:
GET /users/{id})Vì nó máy đọc được, công cụ có thể dùng để sinh client, validate request và giữ đội ngũ đồng bộ.
FastAPI phục vụ hai trang tài liệu thân thiện ngay lập tức:
Trong dự án FastAPI điển hình, bạn sẽ tìm thấy chúng tại:
/docs (Swagger UI)/redoc (ReDoc)Khi bạn thay đổi path parameters, request models, response models hoặc quy tắc xác thực, schema OpenAPI (và trang docs) cập nhật tự động. Không cần bước “bảo trì tài liệu” riêng.
Một app FastAPI có thể rất nhỏ mà vẫn cảm giác “thực”. Bạn định nghĩa một object Python gọi là app, thêm vài route và chạy server local để thử trong trình duyệt.
Ví dụ nhỏ nhất có ích:
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
return {"message": "Hello, FastAPI"}
Chỉ vậy thôi: một route (GET /) trả JSON.
Để cảm nhận như một API, ta lưu item vào danh sách. Đây không phải database—dữ liệu sẽ mất khi server khởi động lại—nhưng phù hợp để học.
from fastapi import FastAPI
app = FastAPI()
items = []
@app.post("/items")
def create_item(name: str):
item = {"id": len(items) + 1, "name": name}
items.append(item)
return item
@app.get("/items")
def list_items():
return items
Bạn có thể:
POST /items?name=Coffee để thêm itemGET /items để lấy danh sáchCấu trúc khởi đầu thường là:
main.py (tạo app và routes)requirements.txt hoặc pyproject.toml (dependencies)Bạn thường:
uvicorn main:app --reload)http://127.0.0.1:8000 và thử các endpoint"Dependencies" trong FastAPI là các input dùng chung mà endpoint cần—như session database, user hiện tại, cấu hình app, hoặc tham số query thông dụng. Thay vì tạo hoặc phân tích chúng trong mỗi route, bạn định nghĩa một lần và FastAPI cung cấp khi cần.
Một dependency thường là hàm (hoặc class) trả về giá trị endpoint có thể dùng. FastAPI sẽ gọi nó, xác định những gì nó cần (dựa trên tham số) và tiêm kết quả vào hàm xử lý của bạn.
Điều này thường gọi là dependency injection, nhưng bạn có thể nghĩ đơn giản là: “khai báo thứ bạn cần, và FastAPI sẽ nối dây giúp.”
Không có dependencies, bạn có thể:
Với dependencies, bạn tập trung logic đó. Nếu sau này thay cách tạo DB session hoặc tải user, bạn sửa một chỗ—không phải hàng chục endpoint.
page/limit.Mẫu bạn sẽ thấy trong nhiều app FastAPI:
from fastapi import Depends, FastAPI
app = FastAPI()
def get_settings():
return {"items_per_page": 20}
@app.get("/items")
def list_items(settings=Depends(get_settings)):
return {"limit": settings["items_per_page"]}
Bạn khai báo dependency với Depends(...), và FastAPI truyền kết quả đó vào tham số endpoint. Cách này cũng áp dụng cho các building block phức tạp hơn (như get_db() hoặc get_current_user()), giúp mã sạch hơn khi API lớn dần.
FastAPI không "tự động bảo mật" API của bạn—bạn chọn sơ đồ và nối nó vào endpoint. Tin tốt là FastAPI cung cấp các khối xây dựng (đặc biệt qua hệ thống dependency) giúp các mẫu bảo mật phổ biến dễ triển khai.
Authentication trả lời: “Bạn là ai?” Authorization trả lời: “Bạn được phép làm gì?”
Ví dụ: một user có thể đã xác thực (token hợp lệ) nhưng vẫn không được phép truy cập route dành admin.
X-API-Key). Cần quản lý rotation và thu hồi.FastAPI hỗ trợ các mẫu này qua tiện ích như fastapi.security và tự động đưa chúng vào OpenAPI.
Nếu lưu mật khẩu người dùng, không bao giờ lưu văn bản thuần. Lưu hash chậm có salt (ví dụ bcrypt/argon2 dùng thư viện uy tín). Cân nhắc rate limiting và chính sách khoá tài khoản.
Bảo mật là về chi tiết: lưu token, cài đặt CORS, HTTPS, quản lý bí mật và kiểm tra authorization đúng ở mọi endpoint nhạy cảm. Xem các helper tích hợp như điểm khởi đầu, và kiểm tra kỹ bằng review và test trước khi đưa vào production.
Testing là nơi lời hứa “chạy được trên máy tôi” trở thành sự tự tin để phát hành. Tin tốt: FastAPI xây trên Starlette, nên bạn có công cụ testing mạnh mà không cần nhiều cấu hình.
Unit tests tập trung mảnh nhỏ: một hàm tính toán, một dependency tải user, hoặc một phương thức service giao tiếp DB (thường mock).
Integration tests chạy API end-to-end: bạn gọi endpoint và assert trên toàn bộ HTTP response. Những test này bắt lỗi routing, wiring dependency và vấn đề xác thực.
Một bộ test lành mạnh thường có nhiều unit test (nhanh) và ít integration test (độ tin cậy cao hơn).
Ứng dụng FastAPI có thể test “như một client” bằng TestClient của Starlette, gửi request đến app nội bộ—không cần server riêng.
from fastapi.testclient import TestClient
from app.main import app
client = TestClient(app)
def test_healthcheck():
r = client.get("/health")
assert r.status_code == 200
Test những thứ người dùng và hệ thống khác phụ thuộc:
Dùng dữ liệu dự đoán được, cô lập dịch vụ ngoài (mock hoặc dùng test DB), và tránh trạng thái chia sẻ giữa test. Test nhanh được chạy; test chậm thường bị bỏ qua.
Đưa app FastAPI lên mạng chủ yếu là chọn “runner” phù hợp và thêm vài yếu tố production.
Khi bạn chạy uvicorn main:app --reload local, đó là thiết lập dev: tự reload, lỗi chi tiết, và cấu hình ưu tiên tiện lợi.
Trong production, thường chạy Uvicorn không reload, thường bên dưới một process manager (như Gunicorn với worker Uvicorn) hoặc sau reverse proxy. Mục tiêu là ổn định: restart có kiểm soát, hiệu năng dự đoán và mặc định an toàn hơn.
Mẫu phổ biến:
Điều này cho phép một codebase triển khai cho nhiều môi trường mà không sửa file.
Trước khi gọi là “xong”, xác nhận bạn có:
/health cho monitoring và load balancer.Nếu bạn chuyển từ “chạy local” sang “đủ điều kiện phát hành”, cũng hữu ích khi tiêu chuẩn hóa cách tạo và quản lý hợp đồng API. Một số đội ghép OpenAPI của FastAPI với luồng tự động—ví dụ sinh client, validate request trong CI và deploy nhất quán. Công cụ như Koder.ai cũng có thể phù hợp giai đoạn này: bạn mô tả API mong muốn qua chat, lặp nhanh endpoints và models, rồi export source cho pipeline review/deploy thông thường.
FastAPI là lựa chọn mạnh nếu bạn muốn cách sạch, hiện đại để xây REST API bằng Python—đặc biệt nếu bạn quan tâm tới model request/response rõ ràng và hành vi dự đoán khi API lớn dần.
FastAPI thường phù hợp khi:
FastAPI không phải lúc nào cũng là câu trả lời đơn giản nhất:
FastAPI có thể rất nhanh trong thực tế, nhưng tốc độ phụ thuộc vào các lần gọi database, độ trễ mạng và logic nghiệp vụ. Mong đợi throughput và latency tốt cho workload API thông thường—chỉ đừng coi framework một mình sẽ “sửa” I/O chậm hoặc truy vấn hiệu năng kém.
Nếu FastAPI phù hợp, hãy tập trung vào routing patterns, Pydantic models, tích hợp database, task nền và xác thực cơ bản.
Lộ trình thực dụng là xây vài endpoint nhỏ, rồi mở rộng với dependencies tái sử dụng và tests khi API lớn dần. Nếu muốn tăng tốc scaffold ban đầu (routes, models và cấu trúc sẵn sàng deploy), cân nhắc workflow vibe-coding—ví dụ vẽ endpoint ở “planning mode” rồi lặp từ một spec duy nhất. Đó là nơi Koder.ai có thể hữu ích: bạn prototype app hướng API từ chat, tinh chỉnh mã được tạo và export khi sẵn sàng chạy như bất kỳ dự án chuẩn nào.
FastAPI là một framework web Python để xây API với rất ít boilerplate. Bạn viết các hàm endpoint (ví dụ @app.get("/users")) và FastAPI đảm nhiệm routing, phân tích request, xác thực và trả về JSON.
Một lợi ích chính là type hints và các model Pydantic của bạn đóng vai trò như hợp đồng rõ ràng cho những gì API chấp nhận và trả về.
API là một tập hợp các URL (endpoints) mà phần mềm khác có thể gọi để trao đổi dữ liệu.
Ví dụ: client có thể yêu cầu dữ liệu thời tiết bằng GET /weather?city=Berlin, và server phản hồi bằng JSON có cấu trúc. Client không cần truy cập trực tiếp vào database — nó chỉ dùng phản hồi từ API.
Routing ánh xạ một phương thức HTTP + đường dẫn đến một hàm Python.
Trong FastAPI bạn thường dùng các decorator:
@app.get("/items") cho thao tác đọc@app.post("/items") cho thao tác tạo@app.put("/items/{id}") để cập nhật/thay thếPath parameters là phần của cấu trúc URL và thường dùng để xác định một tài nguyên cụ thể (bắt buộc).
GET /users/42 → 42 là path parameterQuery parameters được nối sau ? và thường là bộ lọc hoặc tuỳ chọn.
Các model Pydantic định nghĩa hình dạng và quy tắc của dữ liệu (kiểu, trường bắt buộc, ràng buộc). FastAPI dùng chúng để:
Nếu xác thực thất bại, FastAPI thường phản hồi 422 Unprocessable Entity kèm payload lỗi chi tiết cho biết trường nào bị sai.
FastAPI tự động sinh ra định nghĩa OpenAPI từ các endpoint, type hints và model bạn viết.
Bạn thường có tài liệu tương tác miễn phí:
/docs/redocVì schema được sinh ra từ mã, tài liệu sẽ luôn đồng bộ khi bạn thay đổi đường dẫn, model hoặc quy tắc xác thực.
Dùng async def khi endpoint của bạn dành nhiều thời gian chờ I/O (gọi database, gọi dịch vụ ngoài, đọc/ghi file).
Dùng def khi:
Pha trộn cả sync và async trong cùng ứng dụng là chuyện thường thấy.
Dependencies là các “khối xây dựng” tái sử dụng mà FastAPI tiêm vào endpoint qua Depends().
Chúng thường dùng cho:
Cách này giảm lặp lại và tập trung logic chung vào một nơi duy nhất.
FastAPI không tự động bảo mật cho bạn — bạn chọn phương thức và áp dụng cho endpoint.
Các mẫu phổ biến:
Lưu ý cơ bản:
Để test, bạn có thể dùng TestClient của FastAPI/Starlette để gọi API trong tiến trình (không cần server riêng).
Những điều thực tế cần kiểm tra:
Khi deploy, chạy một server ASGI (thường là Uvicorn; đôi khi kèm Gunicorn hoặc reverse proxy) và bổ sung essentials: logging, health checks (ví dụ ), timeouts, và cấu hình theo môi trường.
@app.delete("/items/{id}")Điều này giúp bề mặt API của bạn dễ đọc trực tiếp từ mã nguồn.
GET /users?limit=10&active=true → limit, active là query parameters/health