Giới thiệu Forge: Pipeline mã nguồn mở tự động tạo SDK, CLI và tài liệu

Hôm nay, chúng tôi giới thiệu Forge, một phương pháp tiếp cận mới trong việc tạo SDK, CLI, tài liệu và thư viện. Forge là một pipeline tạo mã nguồn mở, có khả năng tùy biến (pluggable) mà bất kỳ ai cũng có thể triển khai và chạy miễn phí.

Forge vẫn đang trong giai đoạn đầu phát triển, nhưng đã tạo ra được các đầu ra cần thiết cho cf CLI, và trong vài tháng tới, nó sẽ là nền tảng cho tài liệu API, SDK của Cloudflare và nhiều thứ khác nữa.

Chúng tôi xây dựng Forge vì chính chúng tôi cần nó để phục vụ các tác nhân (agents) như những khách hàng của mình. Giờ đây, chúng tôi mở mã nguồn nó vì tin rằng mọi người đều nên có khả năng tạo ra tất cả các giao diện mà các tác nhân cần. Trước đây, chỉ các sản phẩm dành cho nhà phát triển mới cần CLI, API SDK, máy chủ MCP, cùng với các tài liệu tương ứng chất lượng. Hiện nay, đây đã là những tiêu chuẩn bắt buộc cho mọi sản phẩm.

API của chúng tôi đã vượt quá khả năng của các trình tạo mã cũ

API của Cloudflare có hơn 3.500 thao tác, và hàng trăm dịch vụ vận hành các API này được viết bằng nhiều ngôn ngữ khác nhau, bao gồm Rust, Go, TypeScript và Python. Khi bắt đầu xây dựng CLI cho toàn bộ API của Cloudflare, bao gồm cả SDK và tài liệu API, chúng tôi cần một pipeline tạo mã có thể xử lý quy mô này. Pipeline đó cần đủ linh hoạt để hoạt động trên nhiều ngôn ngữ và phù hợp với cách thức vận hành của từng đội ngũ kỹ thuật.

Chúng tôi cần một cách để giảm bớt gánh nặng phối hợp giữa các đội ngũ. Khi một đội ngũ sản phẩm của Cloudflare thực hiện thay đổi API, họ cần có khả năng sử dụng bản dựng thử nghiệm của CLI, SDK và trang tài liệu toàn hệ thống Cloudflare sẽ được tạo ra, trước khi hợp nhất thay đổi đó và gửi đến khách hàng. Chúng tôi cần đảm bảo họ không vô tình làm hỏng pipeline tạo mã. Và chúng tôi cần một hệ thống có thể mở rộng để tạo ra nhiều thứ hơn là chỉ SDK, từ Cap‘n Web đến MCP và hơn thế nữa.

Chúng tôi đã thử nghiệm một số sản phẩm lưu trữ (hosted products) nhằm giải quyết vấn đề này và đã dựa vào một số công cụ trong môi trường sản xuất. Không công cụ nào giải quyết triệt để vấn đề cho chúng tôi, và một số đã ngừng hoạt động hoàn toàn. Một đội ngũ có thể hợp nhất thay đổi vô tình làm hỏng pipeline, đội ngũ khác lại phát hiện ra điều này vào thời điểm phát hành, và chúng tôi đã tốn quá nhiều thời gian để xử lý các công cụ lưu trữ mà chúng tôi không thể kiểm soát, cũng như phối hợp thay đổi giữa các đội ngũ và nhà cung cấp.

Đó là lý do chúng tôi bắt đầu xây dựng Forge.

Forge tìm cách khắc phục tất cả những vấn đề này: nó chạy trong CI, trên các kho lưu trữ API của từng đội ngũ, giống như trình đánh giá mã AI và các pipeline kiểm thử của chúng tôi. Nó kiểm tra lỗi (lint) mọi thay đổi, sau đó tạo ra các bản dựng thử nghiệm của CLI, tài liệu và SDK với các thay đổi của bạn được làm nổi bật để bạn có thể cài đặt và kiểm thử. Tiền đề này giống với Workers Previews: một bản dựng thử nghiệm đầy đủ cho mọi thay đổi, nhưng được áp dụng cho việc tạo SDK ở quy mô lớn, ngay cả khi bề mặt API được phân tán trên hàng trăm dịch vụ và kho lưu trữ. Đó là những gì Forge hướng tới.

Các bộ chuyển đổi (transformers) của Forge có thể tạo ra bất cứ thứ gì, bao gồm cả Cap’n Web

Cloudflare có nhiều lý do hơn hầu hết các đơn vị khác để muốn một trình tạo mã có thể vượt xa các ngôn ngữ mục tiêu thông thường. Cap’n Web là hệ thống RPC của Cloudflare cho phép TypeScript gọi một API từ xa như thể đang gọi một phương thức cục bộ:

// Authenticate, get the user's ID, fetch their profile, and fetch every friend's profile...
let authed = api.authenticate(apiToken);
let profile = api.getUserProfile(authed.getUserId());
let friends = authed.getFriendIds().map(id => api.getUserProfile(id));

// ...in a *single* request
let [me, myFriends] = await Promise.all([profile, friends]);

Forge giúp việc lấy đặc tả OpenAPI và tạo Cap’n Web trực tiếp trở nên khả thi. Điều này mở ra cánh cửa cho việc tạo bindings từ Workers đến các API khác. Xét cho cùng, các bindings trong runtime của Workers được triển khai dưới dạng các Workers cung cấp các phương thức RPC.

Điều này không chỉ giới hạn ở Cap’n Web: các công cụ phổ biến khác mà bạn có thể đang sử dụng cũng cần điều tương tự. Nếu bạn sử dụng TanStack Query, lý tưởng nhất là bạn muốn có thể tạo các bindings TanStack Query cho ứng dụng của mình, được xây dựng trực tiếp từ chính API của bạn. Luôn cập nhật, luôn được xác thực dựa trên API thực tế của bạn. Điều tương tự cũng đúng với việc tạo các lược đồ Zod hoặc Valibot, máy chủ MCP, hoặc bất kỳ thứ gì khác giúp việc sử dụng API của bạn trở nên dễ dàng hơn.

Điều này khả thi vì các trình tạo mã của Forge rất linh hoạt. Chúng được xây dựng để luân chuyển thông tin từ đầu ra này sang đầu ra khác.

Các bộ chuyển đổi của Forge có thể được liên kết với nhau: tạo đầu ra từ các đầu ra khác

Chúng tôi đã thiết kế Forge theo hướng pluggable (có thể cắm thêm), hỗ trợ nhiều loại đầu vào và đầu ra. Forge cung cấp các trình tạo CLI, SDK và tài liệu, nhưng không có gì ngăn cản bạn thêm một bộ chuyển đổi để tạo ra một gói thư viện cụ thể hoặc thậm chí là một bảng điều khiển hoặc ứng dụng hoàn chỉnh. Forge hiện hỗ trợ OpenAPI làm loại đầu vào, nhưng chúng tôi đã thiết kế nó để cho phép AsyncAPI, GraphQL, Cap’n Proto, Protobuf hoặc các định dạng đầu vào khác trong tương lai.

Đây không chỉ là vấn đề tương thích: nó cho phép bạn liên kết các mục tiêu, sử dụng đầu ra của mục tiêu này để tạo ra mục tiêu khác. Điều này phổ biến ở các trình tạo mã khác, nơi các mục tiêu CLI và Terraform được tạo ra từ Go SDK. Nhưng điều còn thiếu, và là thứ mà Forge cung cấp, là cách để người dùng tự kiểm soát hệ thống liên kết này.

Chúng tôi cần một giải pháp cho chính mình, vì cf CLI của chúng tôi được viết bằng TypeScript, thứ mà các trình tạo SDK khác thường không liên kết để tạo CLI. Nhưng tình huống của chúng tôi khiến chúng tôi nhận ra vấn đề sâu xa hơn: tại sao bất kỳ công cụ tạo SDK nào cũng phải đưa ra quyết định này thay cho bạn? Có lẽ bạn là một cửa hàng chuyên về Python và bạn muốn CLI được viết bằng Python.

Nếu bạn đang nghĩ "Chà, nhưng ai quan tâm nó có phải là Python hay không? Mã nguồn được tạo tự động mà," thì đó là vì CLI rất khác biệt. CLI thường giới thiệu các hành vi chỉ có ở cục bộ mà sẽ không hợp lý trong một SDK. Những hành vi mà bạn tự viết bằng tay vì chúng vốn dĩ không được hỗ trợ bởi bất kỳ lệnh gọi API nào. Ví dụ, cf CLI có các lệnh như cf dev và cf build được thêm vào bên trên phần đầu ra đã tạo. Các lệnh này cần gọi các API TypeScript từ các gói khác như Vite.

Bây giờ hãy thêm tài liệu vào hỗn hợp này. Nếu bạn đang tạo CLI và tài liệu hoàn toàn từ đặc tả OpenAPI, làm thế nào để bạn đưa các lệnh viết tay đó trở lại tài liệu của mình để chúng có thể được ghi chép cùng với phần còn lại?

Chúng tôi không thể tìm thấy công cụ hiện có nào làm được điều này, nhưng đây chính xác là những gì chúng tôi cần cho cf. Vì vậy, chúng tôi đang tích hợp nó vào Forge.

Thay đổi API của bạn mà không làm gián đoạn người dùng

Forge cũng đang giúp chúng tôi thiết lập phiên bản API tốt hơn. API v4 của Cloudflare đã là phiên bản chính duy nhất của chúng tôi trong 10 năm qua. Kể từ đó, có vẻ như chúng tôi chưa ra mắt phiên bản chính mới nào, nhưng theo định nghĩa SemVer, chúng tôi đã thực hiện khá nhiều thay đổi xứng đáng với một phiên bản chính mới. Đồng thời, một số thao tác trên API của chúng tôi có các thẻ ‘v2’ nội bộ hoặc định danh ‘beta’ đã tồn tại lâu hơn vòng đời của phần sản phẩm đó.

Sau nhiều năm với API v4, chúng tôi nhận thức rõ rằng một phiên bản v5 lớn mới sẽ bỏ lại rất nhiều khách hàng phía sau. Đó là lý do tại sao, với việc Forge phát hành các thành phần trong suốt quá trình, chúng tôi đang làm việc trên một phương pháp quản lý phiên bản API cho phép chúng tôi phát hành các phiên bản API chính mới mà không làm hỏng các ứng dụng khách hoặc SDK cũ.

Chúng tôi sẽ sớm có thêm thông tin về các SDK của mình, bao gồm TypeScript, Rust, Python, Go, PHP và Terraform. Đặc biệt là Terraform. Chúng tôi biết rằng việc nâng cấp bất kỳ nhà cung cấp Terraform nào đều đi kèm với sự khắt khe riêng, và chúng tôi sẽ dành sự quan tâm đặc biệt cho quá trình chuyển đổi Terraform.

Các công cụ quan trọng nên mở cho tất cả mọi người

Chúng tôi tin rằng việc xây dựng các công cụ cho API là một phần cốt lõi của Internet, và bạn hoàn toàn có thể thực hiện điều đó mà không cần phụ thuộc vào bất kỳ sản phẩm SaaS nào. Bạn nên là người sở hữu các SDK, CLI và tài liệu của riêng mình. Và nếu bạn tạo ra chúng, bạn phải có quyền làm bất cứ điều gì mình muốn, ở bất cứ đâu bạn muốn, hoàn toàn miễn phí.

Đó là lý do tại sao chúng tôi cung cấp Forge dưới dạng mã nguồn mở theo giấy phép Apache 2.0 đầy cởi mở. Chúng tôi mong muốn mọi người cùng tham gia vào hành trình này và đóng góp cho dự án.

Hoặc không thì sao? Có lẽ bạn muốn giữ mọi thứ cho riêng mình. Cứ tự nhiên! Bạn có thể tự vận hành Forge cho bất kỳ mục đích nào, với các tùy chỉnh cá nhân, hoàn toàn miễn phí và ở chế độ riêng tư.

Lời cảm ơn: Dự án này cũng được hiện thực hóa nhờ vào những nỗ lực thiết kế và triển khai của Dan Carter, Steven Chong, Krishna Paritala và Shelley Jones.