Lesson 2.1: Contract-First Development

Thời lượng: 25 phút
Level: Beginner
Yêu cầu: Kiến thức cơ bản về REST API

Mục tiêu bài học

Sau bài học này, bạn sẽ:

• Phân biệt được Code-First và Contract-First development.
• Hiểu được lợi ích của việc thống nhất Spec trước khi code.
• Biết cách sử dụng OpenAPI (Swagger) làm Single Source of Truth.

Nội dung chính

1. Code-First vs Contract-First

Trong phát triển API, có hai trường phái tiếp cận chính:

2. Tại sao Contract-First là "Xương sống" của Design System?

Backend Design System hướng tới sự nhất quán. Nếu mỗi developer tự viết code rồi mới generate spec, sự nhất quán sẽ phụ thuộc vào kỷ luật cá nhân.

Contract-First ép buộc sự nhất quán:

• Thảo luận trước: Team FE và BE chốt data format trước khi tốn công code.
• Mocking: FE có thể dùng mock server (như Prism) để chạy ngay lập tức.
• Validation: Có thể dùng tool để kiểm tra xem code thực tế có chạy đúng như Spec đã hứa không.

3. Công cụ: OpenAPI Specification (OAS)

OpenAPI (tên cũ là Swagger) là tiêu chuẩn công nghiệp để định nghĩa API.

# Ví dụ một phần của OpenAPI Spec
openapi: 3.0.0
info:
  title: User Service API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Lấy thông tin user theo ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Thành công
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'

Nguyên tắc then chốt

"Spec là nguồn sự thật duy nhất. Code chỉ là bản thực thi của Spec."

Nếu Spec và Code khác nhau, Code là sai (mặc dù nó có thể đang chạy). Mọi thay đổi về Data Format đều phải bắt đầu từ việc cập nhật Spec và được Review bởi các Stakeholders.

Thực hành

Bài tập 1: Thiết kế Spec cho tính năng "Tạo đơn hàng"

Bối cảnh: Bạn cần thiết kế API cho phép người dùng tạo đơn hàng mới.

Yêu cầu:

• Định nghĩa URL path (VD: /orders)
• Định nghĩa Request Body (cần có items, total_price)
• Định nghĩa mã lỗi khi hết hàng (400 Bad Request)

Gợi ý:

paths:
  /orders:
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                items: 
                  type: array
                total_price:
                  type: number

Tình huống thực tế

Scenario 1: Frontend team phải đợi Backend

Bối cảnh: Backend dự kiến mất 1 tuần để hoàn thành API. Frontend team đang ngồi chơi vì không biết API sẽ trả về dữ liệu gì để làm giao diện.

Câu hỏi:

1. Bạn sẽ làm gì để Frontend team có thể bắt đầu làm việc ngay vào ngày mai?
2. Spec cần đạt mức độ chi tiết nào để FE có thể mock dữ liệu chính xác?

Câu hỏi phỏng vấn

Junior Level

1. Q: OpenAPI là gì? A: Là một tiêu chuẩn (specification) dùng để mô tả RESTful API dưới dạng file YAML hoặc JSON, giúp con người và máy móc đều hiểu được mà không cần xem source code.

Senior Level

1. Q: Làm sao để đảm bảo Code luôn tuân thủ Contract trong môi trường Agile thay đổi nhanh? A: Sử dụng Contract Testing. Tích hợp các tool như Dredd hoặc Prism vào CI/CD để validate integration tests. Nếu code trả về format khác Spec, build sẽ fail.

Tóm tắt

Những điều cần nhớ

Bước tiếp theo

Bài tiếp theo: Lesson 2.2: Response Envelope - Tìm hiểu cách đóng gói dữ liệu trả về một cách chuyên nghiệp và nhất quán.

Tiếp tục →