Nói ngắn gọn, quy trình design-first (thiết kế API trước rồi mới viết mã) này lặp lại sau mỗi sprint như sau:

1. Chọn hai người phụ trách phần API của sprint, một người bên backend và một người bên frontend.
2. Hai người cùng viết (hoặc cập nhật) bản đặc tả OpenAPI dựa trên yêu cầu của sprint, rồi rà soát cho đến khi cả hai bên đều đồng ý.
3. Commit bản đặc tả vào repo. Từ lúc này, nó chính là hợp đồng giữa hai bên.
4. CI dựng một máy chủ giả lập (mock server) từ bản đặc tả vừa commit.
5. Frontend làm việc với máy chủ giả lập, trong lúc backend viết các endpoint thật.
6. Khi dịch vụ thật đã được triển khai, bản đặc tả do chính dịch vụ đó sinh ra sẽ là điểm xuất phát cho bản đặc tả của sprint tiếp theo.

Chuyện này bắt nguồn từ đâu

#

Mọi chuyện bắt đầu từ một buổi họp nhìn lại (retrospective). Góp ý hôm đó khá thẳng thắn: gần như không ai nắm được khâu lên kế hoạch API đang diễn ra thế nào. Backend xây endpoint theo cách hiểu yêu cầu của riêng mình, frontend chỉ biết phản hồi (response) của API có cấu trúc ra sao khi mọi thứ đã xong xuôi, và những chỗ vênh nhau chỉ lộ ra lúc tích hợp, đúng thời điểm sửa tốn kém nhất. Đề xuất đưa ra là kéo cả hai bên vào ngay từ giai đoạn lên kế hoạch, và lấy bản đặc tả OpenAPI (OpenAPI schema) làm trục chính cho mọi thứ xoay quanh.

Quy trình

#

Mỗi tuần, chúng tôi chọn ra hai đại diện, một người bên backend và một người bên frontend. Nhiệm vụ của họ là nắm rõ yêu cầu của sprint và chỉnh bản đặc tả OpenAPI dùng cho khâu lên kế hoạch sao cho khớp với yêu cầu đó. Hai người cùng rà soát bản đặc tả, sửa những chỗ chưa khớp, và đến cuối buổi thì cả hai bên đều biết chính xác sẽ xây cái gì, trước khi có ai bắt tay vào làm.

Khi các chỉnh sửa đã chốt xong, bản đặc tả được commit vào kho mã (repo), và quy trình CI/CD sẽ sinh ra API giả lập (mock API) từ tệp yaml đó. Hết sprint, chúng tôi tạo một tệp yaml mới cho yêu cầu API của sprint kế tiếp, và vòng lặp cứ thế tiếp tục.

Ghi chú về công cụ

#

Muốn xem trực quan tệp yaml thì Swagger Editor là đủ: tải tệp lên là bạn sẽ thấy nó hiển thị thành một tài liệu Swagger đàng hoàng.

Quy trình CI/CD cần nhận vào một tệp yaml và dựng máy chủ giả lập từ đó. Prism của Stoplight là một lựa chọn được dùng rộng rãi, và hỗ trợ cả OpenAPI 3.1:

npm install -g @stoplight/prism-cli
prism mock openapi.yaml

Lệnh này phục vụ mọi đường dẫn (path) trong bản đặc tả tại http://127.0.0.1:4010, và trả về đúng các giá trị trong examples của bản đặc tả. Chẳng hạn, gọi GET /lists/10 sẽ nhận được danh sách mẫu trong phần phụ lục. Prism cũng bắt tuân thủ hợp đồng: vì ví dụ có khai báo API key, request nào thiếu header X-API-Key sẽ nhận về mã 401, và đó chính là hành vi mà frontend cần xây dựng theo. Nếu chạy Prism trong container, hãy thêm -h 0.0.0.0 để bên ngoài container truy cập được. openapi-mock là một lựa chọn gọn nhẹ hơn, tự điền dữ liệu ngẫu nhiên vào phản hồi.

Bạn cũng nên kiểm tra lỗi (lint) bản đặc tả trước khi dựng máy chủ giả lập. Như vậy, nếu hợp đồng bị viết sai thì bản build sẽ báo lỗi ngay, thay vì để frontend phải loay hoay không hiểu vì sao. Spectral chỉ cần một tệp quy tắc (ruleset) dài đúng một dòng là chạy được:

npm install -g @stoplight/spectral-cli
echo 'extends: ["spectral:oas"]' > .spectral.yaml
spectral lint openapi.yaml

Cuối cùng, bản đặc tả này chỉ phục vụ khâu lên kế hoạch. Khi API thật đã được triển khai, dịch vụ nên tự sinh ra openapi.json của riêng nó; bạn có thể tải tệp đó về rồi dùng lại cho vòng lên kế hoạch tiếp theo.

Sao phải mất công như vậy

#

Vì làm vậy thì các cuộc tranh cãi sẽ diễn ra ở nơi rẻ nhất có thể. Khi có một kỹ sư frontend và một kỹ sư backend cùng ngồi viết bản đặc tả, những chỗ hiểu lầm sẽ được phát hiện trước khi kịp biến thành mã. Yêu cầu API chỉ cần thống nhất một lần, thay vì phải thương lượng lại giữa sprint. Nhờ có máy chủ giả lập, frontend bắt tay vào làm được ngay chứ không phải ngồi chờ. Và số chi tiết quan trọng bị bỏ sót cũng ít hơn hẳn, vì muốn lọt được thì chúng phải qua mắt hai người, lại còn phải qua một bản hợp đồng giấy trắng mực đen.

Chẳng có gì mang tính cách mạng ở đây cả. Chỉ là kế hoạch được làm cụ thể đến mức máy có thể dựng lại nó thành bản giả lập cho bạn dùng. Và hóa ra, đó cũng chính là mức cụ thể mà một bản kế hoạch cần có.

Phụ lục A - Ví dụ yaml

#

openapi: 3.1.0
info:
  title: MyApp Sprint 3
  description: Planning schema for sprint 3. Drives the mock server only.
  version: 0.3.0
servers:
  - url: https://api-mock.example.com/v1
tags:
  - name: lists
    description: Saved lists feature (PROJ-123)
security:
  - api_key: []
paths:
  /lists:
    get:
      tags: [lists]
      summary: Return the current user's saved lists
      operationId: getLists
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/List'
  /lists/{listId}:
    get:
      tags: [lists]
      summary: Find a list by ID
      operationId: getListById
      parameters:
        - name: listId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
        '404':
          description: List not found
components:
  schemas:
    List:
      type: object
      required: [id, title]
      properties:
        id:
          type: integer
          format: int64
          examples: [10]
        title:
          type: string
          examples: [Weekend reading]
        itemCount:
          type: integer
          examples: [7]
  securitySchemes:
    api_key:
      type: apiKey
      name: X-API-Key
      in: header

Cái vòng chờ đợi

#

Quy trình truyền thống thì chạy tuần tự. Backend thiết kế và xây API, và chỉ khi endpoint đã chạy được thật thì frontend mới bắt đầu tích hợp. Backend chậm ngày nào thì lịch của frontend lãnh đủ ngày đó, mà ngày phát hành thường lại phụ thuộc vào lịch của frontend.

Hợp đồng trước, mã nguồn sau

#

Với quy trình đặc tả trước (schema-first), hai bên bắt đầu gần như cùng lúc. Trước khi có dòng mã nào, toàn bộ cấu trúc của API được đưa vào một bản đặc tả OpenAPI (OpenAPI schema): mọi endpoint, mô hình dữ liệu của yêu cầu và phản hồi, phương thức xác thực và mã lỗi. Tài liệu đó trở thành bản hợp đồng giữa frontend và backend.

Lợi ích thấy ngay. Trước khi tính năng được xây, ai cũng hiểu nó theo cùng một cách. Frontend có thể dựng giao diện trong lúc backend vẫn đang hiện thực các endpoint. Khi có thay đổi thì xử lý cũng nhanh hơn, vì chỉ có một nguồn thông tin chuẩn đã được thống nhất cần cập nhật. Và bạn có thể sinh máy chủ giả lập (mock server) thẳng từ bản đặc tả, nên frontend bắt đầu kiểm thử được ngay cả khi chưa có endpoint thật nào.

Áp dụng thực tế ra sao

#

1. Thu thập yêu cầu, như với bất kỳ việc gì khác.
2. Thiết kế bản đặc tả: endpoint, mô hình yêu cầu/phản hồi, xác thực, mã lỗi.
3. Cho cả frontend lẫn backend cùng rà soát. Đây là lúc bản hợp đồng thể hiện rõ giá trị của nó.
4. Sinh máy chủ giả lập (Swagger và Postman đều làm được) và để frontend tích hợp với bản giả lập đó.
5. Backend hiện thực các endpoint thật theo đúng bản đặc tả.
6. Khi endpoint thật lần lượt xong thì thay dần bản giả lập bằng endpoint thật, đồng thời kiểm thử liên tục để chắc chắn hai bên vẫn làm đúng hợp đồng.
7. Tiếp tục trao đổi với nhau. Bản đặc tả là tài liệu sống, chứ không phải thứ khắc lên bia đá.

Những điểm vướng

#

Tất nhiên cách này cũng có cái giá của nó. Viết một bản đặc tả kỹ lưỡng ngay từ đầu tốn khá nhiều thời gian. Khi yêu cầu thay đổi thì bản đặc tả phải đổi trước, và ảnh hưởng sẽ lan sang cả hai đội. Ngoài ra, ai cũng cần biết dùng OpenAPI và các công cụ đi kèm ở mức cơ bản.

Dù vậy, tôi chưa từng thấy trường hợp nào mà công sức bỏ ra lúc đầu lại tốn hơn mớ hỗn loạn lúc tích hợp mà nó giúp tránh được. Frontend bắt tay vào làm từ ngày đầu tiên, còn các cuộc tranh cãi thì diễn ra trên một bản tài liệu, chứ không phải trên những bản dựng hỏng.