Trong thế giới năng động của vi dịch vụ, mọi thứ đều có thể thay đổi—bất kỳ thành phần nào cũng có thể được viết lại bằng ngôn ngữ khác, sử dụng các khung và kiến trúc khác nhau. Chỉ các hợp đồng mới được giữ nguyên để microservice có thể được tương tác lâu dài với bên ngoài, bất kể những biến đổi bên trong. Và hôm nay chúng ta sẽ nói về vấn đề chọn định dạng để mô tả hợp đồng và chia sẻ các hiện vật mà chúng ta tìm thấy.
Đăng bài đã chuẩn bị и
Dịch vụ vi mô. Khi phát triển Acronis Cyber Cloud, chúng tôi nhận ra rằng mình không thể thoát khỏi chúng. Và việc thiết kế một microservice là không thể nếu không chính thức hóa hợp đồng đại diện cho giao diện của microservice.
Nhưng khi một sản phẩm chứa nhiều thành phần và việc phát triển hợp đồng trở thành một hoạt động thường xuyên, bạn không thể không nghĩ đến việc tối ưu hóa quy trình. Rõ ràng là giao diện (hợp đồng) và triển khai (microservice) phải khớp với nhau, các thành phần khác nhau phải thực hiện những việc giống nhau theo cùng một cách và nếu không có sự ra quyết định tập trung cho tất cả các quyết định này, mỗi nhóm sẽ buộc phải dành thời gian nhiều lần để có được chúng.
Sơ đồ vi dịch vụ của Amazon từ Werner Vogelis, CTO Amazon
Vấn đề nan giải là gì? Trên thực tế, có hai cách để tương tác với các vi dịch vụ - HTTP Rest và gRPC từ Google. Không muốn bị cuốn vào đống công nghệ của Google, chúng tôi đã chọn HTTP Rest. Các chú thích hợp đồng HTTP REST thường được mô tả theo một trong hai định dạng: RAML và OAS, trước đây gọi là Swagger. Do đó, mọi nhóm phát triển đều phải đối mặt với nhu cầu chọn một trong các tiêu chuẩn. Nhưng hóa ra, việc đưa ra lựa chọn này có thể rất khó khăn.
Tại sao cần có chú thích?
Cần có chú thích để người dùng bên ngoài có thể dễ dàng tìm ra những gì có thể thực hiện được với dịch vụ của bạn thông qua giao diện HTTP. Nghĩa là, ở cấp độ cơ bản, chú thích phải chứa ít nhất một danh sách các tài nguyên có sẵn, phương thức HTTP, nội dung yêu cầu, danh sách các tham số, chỉ báo về các tiêu đề được yêu cầu và hỗ trợ, cũng như mã trả về và định dạng phản hồi. Một yếu tố cực kỳ quan trọng của chú thích hợp đồng là mô tả bằng lời nói của họ (“điều gì sẽ xảy ra nếu bạn thêm tham số truy vấn này vào yêu cầu?”, “Trong trường hợp nào mã 400 sẽ được trả về?”)
Tuy nhiên, khi cần phát triển một số lượng lớn vi dịch vụ, bạn muốn trích xuất giá trị bổ sung từ các chú thích bằng văn bản. Ví dụ: dựa trên RAML/Swagger, bạn có thể tạo cả mã máy khách và mã máy chủ bằng một số lượng lớn ngôn ngữ lập trình. Bạn cũng có thể tự động nhận tài liệu về microservice và tải nó lên cổng thông tin dành cho nhà phát triển của mình :).
Ví dụ về mô tả hợp đồng có cấu trúc
Ít phổ biến hơn là việc thực hành thử nghiệm các dịch vụ vi mô dựa trên mô tả hợp đồng. Nếu bạn đã viết cả chú thích và thành phần thì bạn có thể tạo tự động kiểm tra để kiểm tra tính đầy đủ của dịch vụ với nhiều loại dữ liệu đầu vào khác nhau. Dịch vụ có trả về mã phản hồi không được mô tả trong chú thích không? Liệu nó có thể xử lý chính xác dữ liệu rõ ràng là không chính xác không?
Hơn nữa, việc triển khai chất lượng cao không chỉ bản thân các hợp đồng mà còn cả các công cụ trực quan hóa chú thích giúp đơn giản hóa công việc với microservice. Nghĩa là, nếu kiến trúc sư mô tả hợp đồng một cách định tính, dựa trên đó, các nhà thiết kế và nhà phát triển sẽ triển khai dịch vụ trong các sản phẩm khác mà không phải trả thêm chi phí thời gian.
Để kích hoạt các công cụ bổ sung, cả RAML và OAS đều có khả năng thêm siêu dữ liệu không được tiêu chuẩn cung cấp ().
Nhìn chung, khả năng sáng tạo trong việc sử dụng hợp đồng cho microservice là rất lớn... ít nhất là về mặt lý thuyết.
So sánh nhím với rắn
Hiện tại, lĩnh vực phát triển ưu tiên tại Acronis là phát triển Nền tảng mạng Acronis. Acronis Cyber Platform là điểm mới tích hợp các dịch vụ của bên thứ ba với Acronis Cyber Cloud và phần đại lý. Mặc dù chúng tôi hài lòng với các API nội bộ được mô tả trong RAML, nhưng nhu cầu xuất bản API lại đặt ra câu hỏi về sự lựa chọn: tiêu chuẩn chú thích nào là tốt nhất để sử dụng cho công việc của chúng tôi?
Ban đầu, có vẻ như có hai giải pháp - sự phát triển phổ biến nhất là RAML và Swagger (hoặc OAS). Nhưng trên thực tế, hóa ra có ít nhất không phải 2 lựa chọn thay thế mà là 3 lựa chọn trở lên.
Một mặt có RAML - một ngôn ngữ mạnh mẽ và hiệu quả. Nó triển khai phân cấp và kế thừa tốt, vì vậy định dạng này phù hợp hơn với các công ty lớn cần nhiều mô tả - nghĩa là không phải một sản phẩm mà là nhiều dịch vụ vi mô có các phần chung của hợp đồng - sơ đồ xác thực, cùng loại dữ liệu, nội dung lỗi .
Nhưng nhà phát triển RAML, Mulesoft, đã gia nhập tập đoàn API mở, tập đoàn đang phát triển . Vì vậy, RAML đã đình chỉ sự phát triển của nó. Để tưởng tượng hình thức của sự kiện, hãy tưởng tượng rằng những người bảo trì các thành phần chính của Linux đã rời đi để làm việc tại Microsoft. Tình huống này tạo ra các điều kiện tiên quyết để sử dụng Swagger, ứng dụng đang phát triển linh hoạt và trong phiên bản mới nhất - thứ ba - thực tế đã bắt kịp RAML về tính linh hoạt và chức năng.
Nếu không phải vì một mà ...
Hóa ra, không phải tất cả các tiện ích nguồn mở đều được cập nhật lên OAS 3.0. Đối với microservice trong Go, điều quan trọng nhất là thiếu khả năng thích ứng cho phiên bản mới nhất của tiêu chuẩn. Tuy nhiên, sự khác biệt giữa Swagger 2 và Swagger 3 là . Ví dụ: trong phiên bản thứ ba, các nhà phát triển:
- mô tả cải tiến của các sơ đồ xác thực
- Hỗ trợ lược đồ JSON
- nâng cấp khả năng thêm ví dụ
Tình huống thật buồn cười: khi chọn một tiêu chuẩn, bạn cần xem xét RAML, Swagger 2 và Swagger 3 như những lựa chọn thay thế riêng biệt. Tuy nhiên, chỉ Swagger 2 mới hỗ trợ tốt các công cụ OpenSource. RAML rất linh hoạt... và phức tạp, còn Swagger 3 lại được cộng đồng hỗ trợ kém, vì vậy bạn sẽ phải sử dụng các công cụ độc quyền hoặc giải pháp thương mại, thường có xu hướng khá tốn kém.
Hơn nữa, nếu có nhiều tính năng hay trong Swagger, chẳng hạn như một cổng thông tin làm sẵn , trên đó bạn có thể tải lên chú thích và hiển thị chú thích đó với mô tả chi tiết, liên kết và kết nối, thì đối với RAML cơ bản hơn và ít thân thiện hơn thì không có cơ hội như vậy. Có, bạn có thể tìm kiếm thứ gì đó trong số các dự án trên GitHub, tìm một thứ tương tự ở đó và tự mình triển khai nó. Tuy nhiên, trong mọi trường hợp, ai đó sẽ phải duy trì cổng này, cổng này không thuận tiện cho nhu cầu sử dụng cơ bản hoặc thử nghiệm. Ngoài ra, vênh vang còn “vô nguyên tắc” hơn hoặc tự do hơn - nó có thể được tạo ra từ các nhận xét trong mã, tất nhiên, điều này đi ngược lại nguyên tắc đầu tiên của API và không được hỗ trợ bởi bất kỳ tiện ích RAML nào.
Đã có lúc chúng tôi bắt đầu làm việc với RAML như một ngôn ngữ linh hoạt hơn và kết quả là chúng tôi phải tự mình làm rất nhiều việc. Ví dụ: một trong những dự án sử dụng tiện ích trong các bài kiểm tra đơn vị, chỉ hỗ trợ RAML 0.8. Thế là chúng tôi phải gắn thêm nạng để tiện ích có thể “ăn” RAML phiên bản 1.0.
Bạn có cần phải lựa chọn?
Sau khi nỗ lực hoàn thiện hệ sinh thái giải pháp cho RAML, chúng tôi đi đến kết luận rằng chúng tôi cần chuyển RAML thành Swagger 2 và thực hiện tất cả quá trình tự động hóa, xác minh, thử nghiệm và tối ưu hóa tiếp theo trong đó. Đây là một cách hay để tận dụng cả tính linh hoạt của RAML và sự hỗ trợ công cụ cộng đồng từ Swagger.
Để giải quyết vấn đề này, có hai công cụ OpenSource sẽ cung cấp tính năng chuyển đổi hợp đồng:
- là một tiện ích hiện không được hỗ trợ. Trong khi làm việc với nó, chúng tôi phát hiện ra rằng nó có một số vấn đề với các RAML phức tạp “trải rộng” trên một số lượng lớn tệp. Chương trình này được viết bằng JavaScript và thực hiện duyệt đệ quy cây cú pháp. Do kiểu gõ động, việc hiểu mã này trở nên khó khăn nên chúng tôi quyết định không lãng phí thời gian viết các bản vá cho một tiện ích sắp chết.
- - một công cụ của cùng một công ty tuyên bố sẵn sàng chuyển đổi mọi thứ và mọi thứ và theo bất kỳ hướng nào. Đến nay, hỗ trợ đã được công bố cho RAML 0.8, RAML 1.0 và Swagger 2.0. Tuy nhiên, tại thời điểm chúng tôi nghiên cứu, tiện ích vẫn còn ẩm ướt và không sử dụng được. Các nhà phát triển tạo ra một loại , cho phép họ nhanh chóng bổ sung các tiêu chuẩn mới trong tương lai. Nhưng cho đến nay nó không hoạt động.
Và đó chưa phải là tất cả những khó khăn chúng tôi gặp phải. Một trong những bước trong quy trình của chúng tôi là xác minh rằng RAML từ kho lưu trữ chính xác so với thông số kỹ thuật. Chúng tôi đã thử một số tiện ích. Điều đáng ngạc nhiên là tất cả họ đều chửi rủa chú thích của chúng tôi ở những nơi khác nhau và với những từ ngữ xấu hoàn toàn khác nhau. Và không phải lúc nào cũng đúng ý :).
Cuối cùng, chúng tôi đã giải quyết một dự án hiện đã lỗi thời, dự án này cũng có một số vấn đề (đôi khi nó gặp sự cố bất ngờ, có vấn đề khi làm việc với biểu thức chính quy). Vì vậy, chúng tôi không tìm ra cách giải quyết các vấn đề về xác thực và chuyển đổi dựa trên các công cụ miễn phí và quyết định sử dụng tiện ích thương mại. Trong tương lai, khi các công cụ OpenSource trở nên hoàn thiện hơn, vấn đề này có thể được giải quyết dễ dàng hơn. Trong khi đó, đối với chúng tôi, chi phí nhân công và thời gian cho việc “hoàn thiện” dường như còn lớn hơn chi phí của một dịch vụ thương mại.
Kết luận
Sau tất cả những điều này, chúng tôi muốn chia sẻ kinh nghiệm của mình và lưu ý rằng trước khi chọn một công cụ để mô tả hợp đồng, bạn cần xác định rõ ràng những gì bạn muốn từ nó và ngân sách bạn sẵn sàng đầu tư. Nếu chúng ta quên OpenSource, thì đã có một số lượng lớn các dịch vụ và sản phẩm sẽ giúp bạn kiểm tra, chuyển đổi và xác thực. Nhưng chúng đắt tiền, và đôi khi rất đắt. Đối với một công ty lớn, những chi phí như vậy có thể chấp nhận được nhưng đối với một công ty khởi nghiệp, chúng có thể trở thành gánh nặng lớn.
Xác định bộ công cụ mà bạn sẽ sử dụng sau này. Ví dụ: nếu bạn chỉ cần hiển thị hợp đồng, sẽ dễ dàng hơn khi sử dụng Swagger 2, có API đẹp, vì trong RAML bạn sẽ phải tự xây dựng và bảo trì dịch vụ.
Bạn càng có nhiều nhiệm vụ thì nhu cầu về các công cụ sẽ càng lớn và chúng khác nhau đối với các nền tảng khác nhau và tốt hơn là bạn nên làm quen ngay với các phiên bản có sẵn để đưa ra lựa chọn giúp giảm thiểu chi phí của bạn trong tương lai.
Nhưng cần phải thừa nhận rằng tất cả các hệ sinh thái tồn tại ngày nay đều không hoàn hảo. Vì vậy, nếu có những người hâm mộ trong công ty thích làm việc trong RAML vì “nó cho phép bạn bày tỏ suy nghĩ linh hoạt hơn” hoặc ngược lại, thích Swagger vì “rõ ràng hơn” thì tốt nhất nên để họ làm việc chúng là gì Họ đã quen với nó và muốn nó, bởi vì các công cụ ở bất kỳ định dạng nào đều yêu cầu sửa đổi bằng một tệp.
Theo kinh nghiệm của chúng tôi, trong các bài đăng sau, chúng tôi sẽ nói về những bước kiểm tra tĩnh và động mà chúng tôi tiến hành dựa trên kiến trúc RAML-Swagger, cũng như những tài liệu chúng tôi tạo ra từ hợp đồng và cách thức hoạt động của tất cả.
Chỉ những người dùng đã đăng ký mới có thể tham gia khảo sát. , xin vui lòng.
Bạn sử dụng ngôn ngữ nào để chú thích các hợp đồng vi dịch vụ?
-
RAML 0.8
-
RAML 1.0
-
vênh váo 2
-
OAS3 (còn gọi là)
-
Blueprint
-
Khác
-
Không sử dụng
100 người dùng bình chọn. 24 người dùng bỏ phiếu trắng.
Nguồn: www.habr.com