Trang này được dịch từ tài liệu tiếng Anh. Lệnh, định danh và ví dụ giữ nguyên. Runtime 7.24.4 · SDK 2.6.7. Bản tiếng Anh
Tương thích HTTP và OpenAPI
Trạng thái: Đang hoạt động Phạm vi: trạng thái hiện tại Xem xét lần cuối: 2026-09-02 Chủ sở hữu: sdk ax-code
AX Code có hai đường tích hợp:
Tên gói JSR bên dưới đã sẵn sàng phát hành nhưng chưa nhận phiên bản công khai đầu tiên.
- Dùng
@defai-digital/ax-code-sdkcho tích hợp ứng dụng TypeScript và JavaScript bên thứ nhất. - Dùng
@defai-digital/ax-code-sdk/headlesshoặc@defai-digital/ax-code-sdk/grpccho công việc ứng dụng và GUI máy tính bên thứ nhất. - Dùng
ax-code servecộng hợp đồng OpenAPI khi cần một ngôn ngữ khác hoặc một ranh giới tiến trình tương thích. - Dùng Vận chuyển SDK gốc cho công việc GUI máy tính bên thứ nhất khi AX Code sở hữu cả hai đầu vận chuyển.
Đường HTTP/OpenAPI là hạ tầng tương thích và máy khách đã sinh. Nó cho phép Python, Go, Java, Rust và các máy khách khác gọi cùng API máy chủ mà AX Code không cam kết duy trì một gói chính thức đầy đủ cho mọi ngôn ngữ. Không nên coi nó là cầu đặc quyền ưu tiên bên trong một GUI máy tính bên thứ nhất khi hợp đồng gRPC/gốc sẵn có, và nó không còn được phơi như các đường con SDK JavaScript bên thứ nhất.
Chọn một đường
| Nhu cầu | Đường được khuyến nghị | Vì sao |
|---|---|---|
| TypeScript hoặc JavaScript trong cùng tiến trình | Bộ chuyển đổi createAgent() của không gian làm việc nguồn |
Chỉ dùng được khi gói nguồn môi trường chạy AX Code riêng được cố ý phân giải được |
| GUI máy tính/gốc bên thứ nhất | @defai-digital/ax-code-sdk/grpc |
Hợp đồng không tương tác hẹp hơn, phát luồng máy chủ, thân thiện siêu dữ liệu/hạn, và ít phơi bày WebView hơn |
| TypeScript hoặc JavaScript với backend cục bộ | @defai-digital/ax-code-sdk/headless |
Giữ vòng đời và phép chiếu sự kiện có kiểu mà không phơi bề mặt SDK HTTP đầy đủ |
| Python, Go, Java, Rust, hoặc môi trường chạy khác | Sinh một máy khách từ packages/sdk/openapi.json |
Tái sử dụng hợp đồng HTTP mà không thêm bảo trì gói bên thứ nhất cho mọi ngôn ngữ |
| CI, tự động hóa, hoặc tập lệnh một lần | Lời gọi HTTP đối với ax-code serve |
Mô hình triển khai đơn giản và cô lập tiến trình dễ dàng |
Cái gì là chính thức hôm nay
@defai-digital/ax-code-sdklà SDK TypeScript và JavaScript bên thứ nhất; các ranh giới ứng dụng công khai của nó làheadlessvàgrpc.@defai-digital/ax-code-sdk/grpclà mặt tiền vận chuyển không tương tác máy tính/gốc tùy chọn bên thứ nhất.@defai-digital/ax-code-sdk/headlesslà SDK vòng đời/sự kiện TypeScript và JavaScript bên thứ nhất cho ranh giới tiến trình backend cục bộ.packages/sdk/openapi.jsonlà ảnh chụp OpenAPI cho các máy khách HTTP đã sinh.- Máy khách không phải JavaScript đã sinh được hỗ trợ như tích hợp qua HTTP, nhưng chúng không phải gói đã phát hành bên thứ nhất trừ khi có chủ gói, kiểm thử và quy trình phát hành.
Luồng HTTP cơ bản
Khởi động máy chủ:
export AX_CODE_SERVER_PASSWORD="$(openssl rand -base64 24)"
ax-code serve --hostname=127.0.0.1 --port=4096Trợ giúp vòng đời @defai-digital/ax-code-sdk/headless sinh một mật khẩu Basic Auth dùng một lần và nối máy khách được trả về với
tiêu đề Authorization khớp một cách tự động. Người dùng ax-code serve thủ công nên đặt AX_CODE_SERVER_PASSWORD
một cách tường minh và gửi tiêu đề Basic Auth tương ứng. Tài liệu OpenAPI trực tiếp tại /doc và mọi điểm cuối máy chủ chỉ
dùng loopback.
Các trợ giúp backend do SDK quản lý luôn từ chối tên máy mạng như 0.0.0.0. Tùy chọn cũ allowNetworkBind được
giữ để tương thích nguồn nhưng không còn vòng qua chính sách chỉ cục bộ. Vỏ GUI máy tính nên ưu tiên
@defai-digital/ax-code-sdk/grpc hoặc một ranh giới SDK trong tiến trình.
Các trợ giúp môi trường chạy HTTP không còn là đường con SDK JavaScript công khai. Gói vẫn chứa phần nội bộ máy khách đã sinh
vì @defai-digital/ax-code-sdk/headless, phương án dự phòng HTTP của gRPC, và mã môi trường chạy AX Code cũ dùng chúng, nhưng các tích hợp
bên ngoài nên dùng không tương tác, gRPC, hoặc máy khách đã sinh từ ảnh chụp OpenAPI thay vì nhập các giá trị môi trường chạy HTTP
từ @defai-digital/ax-code-sdk.
Kiểm tra sức khỏe máy chủ:
curl http://127.0.0.1:4096/global/healthTạo máy khách đã sinh từ ảnh chụp OpenAPI sau khi xác thực ảnh chụp dưới dạng JSON và OpenAPI:
openapi-python-client generate --path packages/sdk/openapi.jsonoapi-codegen -package axcode -generate types,client packages/sdk/openapi.json > axcode.gen.goopenapi-generator-cli generate -i packages/sdk/openapi.json -g java -o ./ax-code-javaChốt sinh mã
Hãy coi tài liệu OpenAPI là hợp đồng trung lập ngôn ngữ. Đừng bảo trì tay các lớp bọc lớn quanh từng tuyến trừ khi cần một lớp thao tác nhỏ.
Hãy ghim phiên bản AX Code và phiên bản máy khách đã sinh cùng nhau. Nếu lược đồ tuyến máy chủ đổi, hãy sinh lại máy khách và phát hành nó kèm ghi chú tương thích rõ ràng.
Giữ mã đã sinh tách khỏi trợ giúp viết tay. Tệp đã sinh nên dễ thay, còn tệp viết tay chỉ nên giữ xác thực, mặc định, thử lại và các API tiện ích cấp cao hơn.
Giữ hành vi ranh giới dịch vụ. Máy khách không phải JavaScript dùng đường máy chủ HTTP và không nhận createAgent() trong tiến trình, thực thi công cụ tùy chỉnh JavaScript, hay tiện ích @defai-digital/ax-code-sdk/testing.
Hãy bao phủ các phần khó trước khi thăng một máy khách đã sinh lên trạng thái bên thứ nhất:
- Xác thực OpenAPI chạy trong CI.
- Một kiểm thử hợp đồng khởi động
ax-code servevà gọi các tuyến đại diện. - Hành vi phát luồng hoặc SSE được kiểm thử nếu máy khách phơi API sự kiện.
- Tiêu đề giới hạn thư mục và hành vi xác thực được ghi lại.
- Việc phát hành, phiên bản hóa và quyền sở hữu là tường minh.
Gói SDK gồm một chốt cục bộ nhẹ cho ảnh chụp hiện tại:
pnpm run check:openapiLệnh cấp gói cũng dùng được khi làm việc bên trong gói SDK:
pnpm --dir packages/sdk/js run validate:openapiViệc này xác thực rằng packages/sdk/openapi.json là JSON phân tích được, khai báo OpenAPI 3.x, và chứa các tuyến cốt lõi mà máy khách đã sinh cần.