Migrating from Apollo Tooling to GraphQL Codegen at Yelp

Yelp · 2026 · 3. Quy mô lớn · Độ khó: Trung bình — bài gốc

Bối cảnh

• Monorepo React của Yelp (hơn 500 package, hàng chục team) sinh kiểu TypeScript cho mọi query GraphQL vào thư mục __generated__ cạnh component. Năm 2020 họ chọn apollo-tooling vì chạy được ngay không cần cấu hình.
• Tháng 4/2023, Apollo khai tử các lệnh CLI đó. Lỗi đã biết không còn được sửa, gặp sự cố thì khó chẩn đoán.

Thay đổi chính

• Chọn "đổi engine, giữ interface": GraphQL Codegen cấu hình để sinh ra output giống hệt apollo-tooling, thay vì các hướng mới (gql.tada, chế độ native) đòi đổi cú pháp ở mọi component. Có tranh luận về việc nhân dịp hiện đại hoá luôn, nhưng mỗi ý tưởng đều kéo theo chi phí migration cho các team khác.
• Khác biệt phải xoá: tên file (theo operation hay theo component), enum/input inline hay nằm ở file chung, kiểu bọc (Maybe<>, Exact<>), tên kiểu lồng nhau. Code có hàng nghìn import trỏ vào đường dẫn cũ.
• Hai lần thử: (1) "hộp đen": chạy Codegen rồi hậu xử lý bằng script Node (tách file, inline kiểu), chạy được nhưng mong manh. Thêm vào đó là lỗi đồng thời chỉ có ở monorepo lớn: fragment của package C được A và B dùng, nên tới ba process cùng sinh file cho C và thỉnh thoảng ra rác. (2) Fork hai plugin và sửa trực tiếp, quản lý bằng yarn patch.
• Đẩy ngược lên upstream: cộng tác với maintainer đúng lúc họ đang làm v6; codebase lớn của Yelp làm môi trường thử, lộ các trường hợp biên (tên kiểu cho union, enum của fragment ở file ngoài). Bản vá thành tuỳ chọn cấu hình chính thức và một đường migration được hỗ trợ cho mọi người dùng apollo-tooling.
• Chuyển từng lô: script codegen giữ một danh sách package còn dùng công cụ cũ; sửa một lô, xoá khỏi danh sách, gửi PR. Lỗi giảm từ hàng chục nghìn còn vài trăm, sửa phần lớn với trợ giúp của AI. Package có vấn đề có thể thêm lại vào danh sách (chưa phải dùng tới). PR cuối xoá toàn bộ hạ tầng apollo-tooling.

Vì sao

• Theo Yelp: bắt mọi team tự sửa code sẽ thành nhiều tháng điều phối và phản kháng; đội Client Data nhận hết độ phức tạp về mình nên ảnh hưởng chỉ nằm trong một team, developer không đổi một dòng nào.
• Bản vá giữ riêng thì mỗi bản phát hành upstream lại thành một lần merge xung đột.

Bài học cho SWE

• Migration trong suốt (giữ đường dẫn, tên kiểu, cách dùng) đáng công sức thêm ở monorepo nhiều team.
• Danh sách ngoại lệ co dần là cách chuyển từng phần có đường lùi rõ ràng.
• Phần khó nhất có khi là xã hội: tìm chủ sở hữu code qua các lần tái cơ cấu để có người review.

Liên quan

• Yelp 2026 (cùng monorepo, Flow → TypeScript từng package) · Yelp 2026
• Stripe 2022 (một PR lớn, cách ngược lại) · Spotify 2023
• Quản lý fleet và migrate code hàng loạt · Migration không downtime