Khi phát triển ứng dụng Web (Next.js) và Mobile (Expo) cùng chung một monorepo, việc thay đổi API có thể gây ra lỗi ngầm trên một trong hai nền tảng. Dưới đây là quy trình thực tế đã áp dụng thành công trong nhiều dự án sản phẩm. ## 1. Định nghĩa chiến lược phiên bản hóa - Sử dụng tiền tố URL `/v1/`, `/v2/` cho mọi endpoint. - Mỗi phiên bản lớn (major) được tách thành thư mục riêng trong `packages/api/src/routes/v1`, `v2`… - Không bao giờ xóa endpoint cũ cho đến khi tất cả client đã nâng cấp. ## 2. Tách bộ định tuyến (router) theo phiên bản ```ts // packages/api/src/routes/index.ts export { default as v1 } from './v1'; export { default as v2 } from './v2'; ``` Trong `server.ts` của Next.js và `app/_layout.tsx` của Expo, mount từng router theo prefix. Điều này giúp cả hai nền tảng dùng chung code nguồn nhưng vẫn tách biệt logic. ## 3. Viết contract test cho từng phiên bản - Dùng **Pact** hoặc **OpenAPI** schema để sinh contract test tự động. - Mỗi PR thay đổi API phải cập nhật schema và chạy `pnpm test:contract` trên CI. - Nếu test thất bại, CI chặn merge, buộc dev xem xét breaking change. ## 4. Feature flag cho triển khai dần - Tạo package `shared/feature-flags` chứa map `flag -> boolean` đọc từ env hoặc remote config (LaunchDarkly, Unleash). - Bọc logic mới trong `if (flags['new-checkout']) { … }`. - Client Web và Mobile cùng đọc flag từ cùng một source, đảm bảo hành vi đồng bộ. ## 5. Chiến lược depreciation 1. Đánh dấu endpoint cũ bằng header `Deprecation: true` và `Sunset: <date>`. 2. Ghi log cảnh báo ở client khi gọi endpoint deprecated (dùng interceptor Axios / Ky). 3. Thiết lập deadline 3‑6 tháng, sau đó xóa code v1 khỏi monorepo. ## 6. Checklist cho mỗi release - [ ] Cập nhật OpenAPI spec cho phiên bản mới. - [ ] Chạy contract test toàn bộ monorepo. - [ ] Bật feature flag cho nhóm beta. - [ ] Theo dõi metric lỗi 4xx/5xx trên cả Web và Mobile qua OpenTelemetry. - [ ] Gửi thông báo cho team frontend về endpoint deprecated. Áp dụng quy trình này giúp giảm thiểu sự cố "broken API" khi deploy song song Web và Mobile, đồng thời tạo thói quen tài liệu hóa và kiểm thử tự động – yếu tố then chốt cho tốc độ phát triển bền vững.