Nhà phát triển API cần đọc! Giải thích 5 mã lỗi quan trọng được triển khai bằng Swagger
【Tâm sự của nhà phát triển】Những câu chuyện thường gặp khi đối mặt với mã lỗi
"Ủa? Tại sao yêu cầu API này lại trả về lỗi 403..."
Gần đây, tôi đã gặp phải tình huống này trong một dự án. Sau khi nhận được thông báo từ khách hàng rằng "API không hoạt động đúng", tôi vội vàng điều tra và phát hiện đó chỉ là vấn đề đơn giản về token xác thực đã hết hạn. Tuy nhiên, đối với khách hàng, họ chỉ biết "403 là gì?"
Từ trải nghiệm này, tôi nhận ra tầm quan trọng của việc giải thích mã lỗi API một cách dễ hiểu. Đặc biệt trong phát triển API sử dụng Swagger, việc định nghĩa và giải thích mã lỗi phù hợp có ảnh hưởng lớn đến hiệu quả phát triển và trải nghiệm người dùng.
Trong bài viết này, tôi sẽ giải thích ý nghĩa và cách sử dụng thực tế của các mã trạng thái HTTP thường được sử dụng trong Swagger. Hy vọng rằng điều này sẽ hữu ích cho các kỹ sư tham gia vào phát triển API.
Cơ bản về mã lỗi Swagger: 5 trạng thái cần biết
Mã lỗi Swagger về cơ bản tuân theo mã trạng thái HTTP. Đặc biệt quan trọng là 5 mã sau đây.
400 Bad Request: "Yêu cầu của bạn không đúng"
Chỉ ra rằng yêu cầu không hợp lệ và máy chủ không thể xử lý. Ví dụ, có thể là do thiếu trường bắt buộc hoặc dữ liệu có định dạng không đúng.
/users:
post:
summary: API đăng ký người dùng
responses:
'400':
description: Yêu cầu không hợp lệ. Có thể thiếu mục bắt buộc hoặc lỗi định dạng dữ liệu.
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "Email format is invalid"
Trong môi trường phát triển thực tế, điều quan trọng là chỉ ra cụ thể "sai ở đâu". Ví dụ, trả về thông báo lỗi chi tiết như "Định dạng địa chỉ email không hợp lệ" sẽ giúp ích cho các nhà phát triển sử dụng API.
401 Unauthorized: "Cần xác thực"
Chỉ ra rằng cần xác thực để xử lý yêu cầu. Điều này xảy ra khi người dùng chưa đăng nhập hoặc thông tin xác thực không chính xác.
/secure-data:
get:
summary: Lấy dữ liệu được bảo vệ
security:
- bearerAuth: []
responses:
'401':
description: Cần xác thực. Vui lòng cung cấp token truy cập hợp lệ.
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "Authentication required"
Lỗi 401 chỉ ra vấn đề xác thực. Cung cấp lý do cụ thể như "Token không hợp lệ" hoặc "Thông tin xác thực đã hết hạn" sẽ rất hữu ích.
403 Forbidden: "Không có quyền"
Chỉ ra rằng người dùng không có quyền truy cập vào tài nguyên được yêu cầu. Ví dụ, khi không được phép truy cập vào một API cụ thể.
/admin/settings:
put:
summary: Cập nhật cài đặt quản trị viên
responses:
'403':
description: Bạn không có quyền truy cập vào tài nguyên này. Cần quyền quản trị viên.
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "Admin privileges required"
Việc hiểu sự khác biệt giữa 401 và 403 là quan trọng. 401 thể hiện trạng thái "không biết là ai (chưa xác thực)", còn 403 thể hiện trạng thái "biết là ai nhưng không có quyền".
404 Not Found: "Không tìm thấy tài nguyên"
Chỉ ra rằng tài nguyên được yêu cầu không tồn tại. Có thể do lỗi URL hoặc tài nguyên đã bị xóa.
/products/{id}:
get:
summary: Lấy chi tiết sản phẩm
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'404':
description: Không tìm thấy sản phẩm với ID đã chỉ định.
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "Product with ID 123 not found"
Đối với lỗi 404, thay vì chỉ đơn giản là "Không tìm thấy", nếu có thể, việc chỉ ra cụ thể "không tìm thấy tài nguyên nào" sẽ rất hữu ích.
500 Internal Server Error: "Có vấn đề ở phía máy chủ"
Chỉ ra rằng đã xảy ra lỗi trong quá trình xử lý ở phía máy chủ. Điều này có thể do lỗi trong mã hoặc vấn đề cấu hình máy chủ.
/complex-operation:
post:
summary: Thực hiện xử lý phức tạp
responses:
'500':
description: Đã xảy ra lỗi nội bộ máy chủ. Vui lòng liên hệ quản trị viên hệ thống.
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "Internal server error occurred"
requestId:
type: string
example: "req-123456"
Lỗi 500 chỉ ra vấn đề ở phía máy chủ. Trong môi trường sản xuất, cần thận trọng không để lộ thông tin lỗi chi tiết ra bên ngoài, đồng thời nên bao gồm ID yêu cầu để hỗ trợ khắc phục sự cố.
Xử lý lỗi thực tế: Kỹ thuật hữu ích trong thực tế
Kỹ thuật 1: Định dạng phản hồi lỗi nhất quán
Việc sử dụng định dạng phản hồi lỗi nhất quán trong toàn bộ API giúp việc triển khai phía máy khách trở nên đơn giản. Ví dụ:
components:
schemas:
Error:
type: object
properties:
code:
type: string
description: Mã lỗi
message:
type: string
description: Thông báo lỗi có thể đọc được
details:
type: array
items:
type: object
properties:
field:
type: string
message:
type: string
Việc định nghĩa định dạng lỗi chung như vậy giúp các nhà phát triển frontend dễ dàng triển khai xử lý lỗi.
Kỹ thuật 2: Mã lỗi tùy chỉnh dựa trên logic nghiệp vụ
Việc bổ sung mã lỗi tùy chỉnh để thể hiện các trạng thái lỗi chi tiết mà mã trạng thái HTTP không thể biểu thị cũng rất hiệu quả.
/payment:
post:
summary: Xử lý thanh toán
responses:
'400':
description: Xử lý thanh toán thất bại
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Error'
- type: object
properties:
code:
example: "PAYMENT_INSUFFICIENT_FUNDS"
message:
example: "Không thể thanh toán do số dư không đủ"
Việc sử dụng mã tùy chỉnh như "PAYMENT_INSUFFICIENT_FUNDS" cho phép cung cấp thông tin chi tiết mà mã trạng thái HTTP đơn thuần không thể truyền tải.
Kỹ thuật 3: Tài liệu hóa mã lỗi
Hãy tận dụng thế mạnh của Swagger để tài liệu hóa chi tiết mã lỗi và cách xử lý.
components:
schemas:
Error:
type: object
properties:
code:
type: string
description: |
Mã lỗi. Các giá trị sau đây sẽ được thiết lập:
- AUTHENTICATION_FAILED: Xác thực thất bại
- AUTHORIZATION_FAILED: Không có quyền
- RESOURCE_NOT_FOUND: Không tìm thấy tài nguyên
- VALIDATION_ERROR: Giá trị đầu vào không hợp lệ
Kỹ thuật 4: Kiểm tra trạng thái lỗi bằng công cụ
Ngay cả khi backend thực tế chưa hoàn thành, bạn vẫn có thể mô phỏng các trạng thái lỗi khác nhau bằng cách sử dụng các công cụ như máy chủ giả lập. Điều này cho phép các nhà phát triển frontend bắt đầu triển khai xử lý lỗi từ giai đoạn đầu.
# Ví dụ cấu hình máy chủ giả lập
paths:
/users/{id}:
get:
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'404':
description: Không tìm thấy người dùng
content:
application/json:
example:
error: "User with ID 42 not found"
Trong các dự án gần đây, tôi đã sử dụng các công cụ tương thích với đặc tả Swagger/OpenAPI để tạo và quản lý các ví dụ về phản hồi lỗi thông qua giao diện trực quan. Đặc biệt, với các công cụ như Apidog, bạn có thể dễ dàng tạo các ví dụ về mẫu phản hồi lỗi khác nhau bằng cách kéo và thả, giúp thống nhất quy tắc đặt tên và định dạng mã lỗi trong toàn bộ nhóm.
Tóm tắt: Thiết kế mã lỗi hiệu quả nâng cao chất lượng API
Thiết kế mã lỗi trong Swagger không chỉ là công việc kỹ thuật đơn thuần mà còn là yếu tố quan trọng trực tiếp ảnh hưởng đến khả năng sử dụng và độ tin cậy của API. Tóm tắt nội dung đã giới thiệu trong bài viết này:
- Sử dụng phù hợp các mã trạng thái HTTP cơ bản
- Định nghĩa định dạng phản hồi lỗi nhất quán
- Tận dụng mã lỗi tùy chỉnh dựa trên logic nghiệp vụ
- Tài liệu hóa chi tiết mã lỗi và cách xử lý
- Sử dụng công cụ phù hợp để tối ưu hóa quản lý mã lỗi
Việc nắm vững các điểm này giúp thiết kế API dễ hiểu và dễ sử dụng cho cả nhà phát triển và người dùng API.
Việc sử dụng các công cụ dựa trên đặc tả Swagger/OpenAPI (đặc biệt là Apidog) giúp tiêu chuẩn hóa mã lỗi trong toàn bộ nhóm. Tính năng máy chủ giả lập để kiểm tra trạng thái lỗi cũng đóng góp lớn vào việc tối ưu hóa phát triển frontend.
Công cụ và tài nguyên liên quan
- Swagger Editor: Công cụ chính thức cho phép chỉnh sửa trực quan đặc tả API bao gồm mã lỗi
- Apidog: Nền tảng phát triển API hỗ trợ đặc tả Swagger/OpenAPI, giúp quản lý mã lỗi và kiểm tra giả lập dễ dàng
- Postman: Công cụ phổ biến cho kiểm tra API và tạo tài liệu
All Rights Reserved
