Quy ước API
Trang này nói về những quy ước chung khi frontend gọi backend: địa chỉ, dạng phản hồi, cách khai báo endpoint mới và cách đặt tên hook. Dành cho người định thêm hoặc sửa một endpoint.
Vì sao cần quy ước chung
Có hơn 70 endpoint trải trên 12 file. Nếu mỗi file tự quyết định cách nối URL, cách gửi tham số hay cách đọc phản hồi thì rất khó sửa lỗi chung, chẳng hạn như thêm header hoặc xử lý 401. Vì vậy mọi endpoint đi qua cùng một baseApi, một baseQuery và một Axios instance.
WARNING
Địa chỉ backend được viết cứng trong code là http://localhost:8081/api/v1, không đọc từ biến môi trường. Đổi môi trường nghĩa là phải sửa file constant.ts. Xem Biến môi trường.
Đường đi của một request
Interceptor của Axios trả về response.data, nên data mà hook nhận chính là thân phản hồi ApiResponse, không phải đối tượng response của Axios.
Các quy ước
| Hạng mục | Quy ước trong code |
|---|---|
| Địa chỉ | API_BASE_URL trong src/shared/constants/constant.ts |
| Nối URL | axiosBaseQuery nối baseUrl + url thành URL tuyệt đối |
| Timeout | 10 giây (axios.create) |
| Cookie | withCredentials: true, để gửi cookie refresh token |
| Xác thực | Header Authorization: Bearer <access_token> lấy từ localStorage, gắn ở request interceptor |
| Content-Type | application/json, trừ khi data là FormData |
| Upload file | Gửi FormData, không đặt Content-Type thủ công |
| Cache tag | Khai báo trong tagTypes của baseApi |
Cơ chế làm mới token khi gặp 401 nằm ở Xác thực.
Dạng phản hồi
ApiResponse<T> được định nghĩa ở src/shared/base/api-response.base.ts:
| Field | Kiểu | Bắt buộc | Ý nghĩa |
|---|---|---|---|
statusCode | number | string | Có | Mã trạng thái backend ghi trong thân phản hồi |
message | string | null | Có | Thông điệp từ backend, có thể null |
data | T | Không | Dữ liệu chính |
timestamp | string | null | Không | Thời điểm phản hồi |
error | string | string[] | Không | Thông tin lỗi nếu có |
Danh sách phân trang có dạng PaginatedResult<T>, xem Phân trang và lọc.
Thêm một endpoint
- Nếu nhóm API chưa có, tạo
src/features/<tên>/redux/<tên>.api.tsvà gọibaseApi.injectEndpoints. - Khai báo
builder.querycho thao tác đọc hoặcbuilder.mutationcho thao tác ghi, ghi rõ kiểuApiResponse<...>. - Thao tác đọc dùng
providesTags, thao tác ghi dùnginvalidatesTags. Tag mới phải được thêm vàotagTypestrongsrc/lib/redux/api.ts. - Export hook do RTK Query sinh ra.
- Nếu logic phức tạp (toast, đóng dialog), bọc trong một hook ở
src/hooks/.
// src/features/job/redux/job.api.ts (rút gọn)
export const jobApi = baseApi.injectEndpoints({
endpoints: (builder) => ({
getJob: builder.query<ApiResponse<Job>, string>({
query: (id) => ({ url: `/jobs/${id}`, method: "GET" }),
providesTags: (result, error, id) => [{ type: "Job", id }],
}),
}),
});Đặt tên
| Thành phần | Quy ước | Ví dụ |
|---|---|---|
| Endpoint | Động từ + danh từ, camelCase | getJob, createJob, bulkDeleteJobs |
| Hook đọc | use<Endpoint>Query | useGetJobQuery |
| Hook ghi | use<Endpoint>Mutation | useCreateJobMutation |
| Schema form | <Tên>FormData trong schemas/ | CreateJobFormData |
Cách dựng tham số
Code không dùng một cách duy nhất. Có hai kiểu đang tồn tại cạnh nhau:
| Kiểu | Ví dụ | Ghi chú |
|---|---|---|
| Tự nối chuỗi query | getJobs dựng page=..&limit=.. rồi nối filter và sort | Dùng cho các danh sách quản trị theo kiểu lọc của backend |
Truyền params cho Axios | searchJobs truyền đối tượng JobSearchParams | Axios tự mã hóa query string |
Source code liên quan
src/lib/redux/api.ts:baseApi,tagTypessrc/lib/axios/axios-base-query.ts: nối URL và chuẩn hóa lỗisrc/lib/axios/axios-instance.ts: timeout, interceptor, tokensrc/shared/base/api-response.base.ts:ApiResponsesrc/shared/constants/constant.ts:API_BASE_URLsrc/features/job/redux/job.api.ts: ví dụ đầy đủ
Backend mô tả định dạng phản hồi và lỗi ở Tổng quan API của backend.
Đọc tiếp: Xử lý lỗi, Phân trang và lọc, Cache và invalidation.
