Đó là khoảnh khắc khi bạn vui vẻ cấu trúc lại chương trình phụ trợ của mình và sau đó bạn đạt được một phương thức điểm cuối. Đột nhiên một làn sóng lo lắng ập đến trong bạn. Điểm cuối này thậm chí còn được sử dụng không? Tất cả các trường đó trong DTO này có được sử dụng trên giao diện người dùng không? Giao diện người dùng sẽ ngắt ở đâu khi tôi đổi tên trường này? Với tất cả những câu hỏi đó, không có gì lạ nếu bạn chỉ từ bỏ và ngừng tái cấu trúc thêm.

Đừng mất hy vọng. Có nhiều cách để kiểm tra loại mã khách hàng của bạn với API máy chủ của bạn. Tôi sẽ chỉ cho bạn một cách đơn giản đó là sự bất khả tri của ngăn xếp máy chủ hoàn toàn. Nó dựa trên các công cụ được xây dựng xung quanh Đặc tả OpenAPI (trước đây là Đặc tả Swagger).

Ý tưởng chung là như sau: tạo một máy khách Typecript từ mô tả OpenAPI của các điểm cuối máy chủ. Bạn không cần phải tự mình viết đặc tả API. Có các plugin tạo nó cho bạn cho bất kỳ ngăn xếp máy chủ phổ biến nào .

Hãy chuyển sang một ví dụ cụ thể.
Tôi sẽ sử dụng Spring Boot cho phía máy chủ. Đối với giao diện người dùng, tôi đã chọn React yêu quý của mình .

Chúng ta cần bắt đầu ở phần phụ trợ. Đối với người mới bắt đầu, bạn cần thêm các phần phụ thuộc này vào dự án Spring Boot của bạn pom.xml:

và định cấu hình nó bằng cách đặt cấu hình này trong gói gốc của bạn

Làm xong điều này, sẽ có một điểm cuối mới - /v2/api-docs. Nó phục vụ JSON khổng lồ này mô tả tất cả các điểm cuối của bạn. Nó chứa tất cả thông tin cần thiết để tạo ra một ứng dụng khách hoàn chỉnh, được đánh máy đầy đủ.

Các công cụ để làm điều đó được cung cấp bởi dự án openapi-generator . Có các tùy chọn để chạy nó trực tiếp , thông qua Docker hoặc gói npm . Nếu bạn đã cài đặt JRE, thì tùy chọn cuối cùng sẽ là tùy chọn dễ dàng nhất:

Một vài lưu ý ở đây. Chúng tôi đang sử dụng generatetác vụ từ @openapitools/openapi-generator-cligói. Với việc -ichúng tôi xác định nơi lấy đặc tả API và -gchúng tôi chọn typescript-fetchmẫu cho ứng dụng khách đã tạo của chúng tôi từ tất cả các mẫu có sẵn (tất nhiên là bao gồm một mẫu cho Angular). Tùy chọn cuối cùng ( -o) chỉ định thư mục đầu ra cho các tệp được tạo

Bây giờ chúng ta hãy lấy bộ điều khiển Spring đơn giản này:

Xác thực javax và chú thích swagger được sử dụng ở đây có tác động đến đặc tả API được tạo. Hãy xem phân đoạn tương ứng của JSON đã tạo:

Từ nó, các bản ghi sau đây được tạo ra:

Như bạn có thể thấy các trường được đánh dấu @NotNullđược tạo thành các trường bắt buộc (1). Văn bản "Họ của người dùng" từ @ApiModelPropertyđược sử dụng trong tài liệu bổ sung của lastName(2). Một điều khác cần lưu ý ở đây - tên enum Typescript được tạo dựa trên tên trường ( User.roles), không phải tên enum từ Java. Điều này là do tên của nó không được bao gồm ở bất kỳ đâu trong JSON tại /v2/api-docs.

Bên cạnh mô hình được tạo, cũng có các phương thức tương ứng với tất cả các điểm cuối có sẵn. Trong trường hợp này, có UserResourceApilớp với allUsersUsingGETphương thức.

Nếu bạn nhìn kỹ vào tên được tạo của phương thức, bạn sẽ nhận thấy rằng nó có nguồn gốc trực tiếp từ tên phương thức Java. Điều này hơi phản trực quan. Các thay đổi trong đường dẫn điểm cuối không yêu cầu thay đổi mã ở phía máy khách. Có vẻ như những thay đổi nội bộ đối với tên phương thức máy chủ triển khai điểm cuối dẫn đến những thay đổi vi phạm trong ứng dụng khách đã tạo.

Có tất cả những điều đó, hãy xem việc sử dụng ứng dụng khách được tạo trông như thế nào:

Đầu tiên đặt URL cơ sở cho tất cả các lệnh gọi API (1), sau đó khởi tạo trình bao bọc API cho tài nguyên (2). Cuối cùng, gọi các điểm cuối cụ thể (3) bằng cách sử dụng các phương thức được nhập đầy đủ.

Đó là nó. Bây giờ bạn có một cách để đảm bảo rằng mã khách hàng của bạn hoàn toàn nhất quán với API phụ trợ.

Bản tóm tắt

Với thiết lập này, bạn có thể sử dụng trình biên dịch Typecript để xác minh rằng bạn đang gọi đúng URL điểm cuối API, chuyển các tham số phù hợp và diễn giải phản hồi đúng cách. Điều này thực sự có thể làm tăng sự tự tin trong cơ sở mã của bạn.

Cấu hình đơn giản này sẽ hoạt động tốt cho một dự án nhỏ, nhưng không đủ cho các nhóm lớn hơn. Giải pháp cuối cùng sẽ là tạo và xuất bản gói npm client typecript trên máy chủ CI / CD như một phần của việc xây dựng chương trình phụ trợ. Nhưng điều này xứng đáng là một bài đăng trên blog riêng biệt. Tuy nhiên, bạn luôn có thể bắt đầu với giải pháp đơn giản này và sau đó chuyển sang một đường ống tiên tiến hơn sau này.