Dự án Smithy

Smithy là một ngôn ngữ định nghĩa giao diện để mô tả các dịch vụ và dữ liệu mà chúng trao đổi. Trình tạo dự án Smithy tạo ra một dự án chứa một mô hình Smithy.

Có hai loại dự án Smithy:

Service (--type=service) — một mô hình định nghĩa một dịch vụ và các hoạt động của nó. Đây là những gì trình tạo ts#api --framework=smithy tạo cho bạn cùng với một triển khai TypeScript.
Shape library (--type=shapes) — một mô hình định nghĩa các shape có thể tái sử dụng nhưng không có dịch vụ. Kết nối một shape library với các dự án Smithy của bạn để chia sẻ các shape giữa chúng, thay vì nhân bản các định nghĩa trong mỗi dự án.

Cách sử dụng

pnpm nx g @aws/nx-plugin:smithy#project --name=my-shapes

yarn nx g @aws/nx-plugin:smithy#project --name=my-shapes

npx nx g @aws/nx-plugin:smithy#project --name=my-shapes

bunx nx g @aws/nx-plugin:smithy#project --name=my-shapes

Bạn cũng có thể thực hiện chạy thử để xem những tệp nào sẽ bị thay đổi

pnpm nx g @aws/nx-plugin:smithy#project --name=my-shapes --dry-run

yarn nx g @aws/nx-plugin:smithy#project --name=my-shapes --dry-run

npx nx g @aws/nx-plugin:smithy#project --name=my-shapes --dry-run

bunx nx g @aws/nx-plugin:smithy#project --name=my-shapes --dry-run

Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
Mở Nx Console trong VSCode
Nhấp Generate (UI) trong phần "Common Nx Commands"
Tìm kiếm @aws/nx-plugin - smithy#project
Điền các tham số bắt buộc
- name: my-shapes
Nhấp Generate

Tùy chọn

Tham số	Kiểu	Mặc định	Mô tả
name Bắt buộc	string	-	Tên dự án Smithy
type	service \| shapes	service	Loại dự án Smithy cần tạo. Chọn giữa service (một model với service shape, sẵn sàng cho việc triển khai) và shapes (một thư viện shape chứa các shape có thể tái sử dụng, được chia sẻ giữa nhiều dự án Smithy).
serviceName	string	-	Tên của Smithy service của bạn. Sử dụng tên được cung cấp theo mặc định. Không áp dụng cho thư viện shape.
namespace	string	-	Namespace cho Smithy API. Mặc định là scope của monorepo của bạn
directory	string	packages	Thư mục cha nơi dự án Smithy được đặt.
subDirectory	string	-	Thư mục con nơi dự án Smithy được đặt. Mặc định là tên dự án.
preferInstallDependencies	boolean	true	Có nên cài đặt các dependencies sau khi generator chạy hay không. Đặt thành false để hoãn việc cài đặt khi chạy nhiều generator liên tiếp (việc cài đặt vẫn sẽ chạy nếu cần thiết để các generator tiếp theo có thể tính toán Nx project graph); cài đặt một lần vào cuối.

Kết quả của Trình tạo

Shape Library

Thư mụcmy-shapes
- Thư mụcsrc
  - main.smithy Your shared shape definitions
- smithy-build.json Smithy build configuration
- project.json Project configuration and build targets

Một shape library định nghĩa các shape và không có gì khác:

$version: "2.0"

namespace com.example

structure Customer {
    @required
    id: String

    name: String
    email: String
}

Vì một shape library không có dịch vụ, smithy-build.json của nó không cấu hình việc tạo mã — việc xây dựng nó sẽ xác thực mô hình và tập hợp nó thành một tệp mô hình JSON duy nhất tại dist/<my-shapes>/build/model.json.

Service

Thư mụcmy-service
- Thư mụcsrc
  - main.smithy Your service definition
  - Thư mụcoperations
    echo.smithy An example operation
- smithy-build.json Smithy build configuration, including code generation
- ssdk.rolldown.config.mjs Bundles the generated TypeScript Server SDK
- project.json Project configuration and build targets

Một mô hình service định nghĩa một shape service và các hoạt động mà nó cung cấp:

$version: "2.0"

namespace com.example

use aws.protocols#restJson1

@title("MyService")
@restJson1
service MyService {
    version: "1.0.0"
    operations: [
        Echo
    ]
}

Việc xây dựng một dự án service tạo ra một đặc tả OpenAPI và một TypeScript Server SDK vào dist/<my-service>/build/.

Xây dựng

Các dự án Smithy được xây dựng bằng Smithy CLI, công cụ này xác thực mô hình của bạn:

pnpm nx build my-shapes

yarn nx build my-shapes

npx nx build my-shapes

bunx nx build my-shapes

Trên macOS và Linux, CLI được giải quyết bởi mise, công cụ mà quá trình xây dựng tải về theo yêu cầu, vì vậy không có gì cần cài đặt — nó tải xuống và lưu vào bộ nhớ cache phiên bản đã được ghim lần đầu tiên bạn xây dựng. Trên Windows, đây là một điều kiện tiên quyết mà bạn phải tự cài đặt — xem Xây dựng trên Windows.

Phụ thuộc vào một Shape Library

Việc xây dựng một shape library ghi một mô hình đã được tập hợp vào dist/<my-shapes>/build/model.json. Tệp duy nhất này chứa mọi shape mà thư viện định nghĩa, cùng với bất kỳ shape nào mà nó phụ thuộc vào, vì vậy người tiêu dùng chỉ cần khai báo các thư viện mà nó tham chiếu trực tiếp.

Để phụ thuộc vào một shape library từ một dự án Smithy khác, hãy thực hiện hai thay đổi đối với dự án tiêu dùng:

Thêm mô hình đã được xây dựng của thư viện vào imports trong smithy-build.json của dự án tiêu dùng. Các đường dẫn là tương đối với tệp đó, vì vậy số lượng phân đoạn ../ khớp với độ sâu lồng nhau của dự án tiêu dùng — ba cho packages/my-api/model bên dưới:
```
{
  "version": "1.0",
  "sources": ["src/"],
  "imports": ["../../../dist/packages/my-shapes/build/model.json"],
  ...
}
```
Thêm target build của thư viện làm phụ thuộc của target compile của dự án tiêu dùng trong project.json của nó, để mô hình tồn tại trước khi người tiêu dùng xây dựng:
```
{
  "targets": {
    "compile": {
      "dependsOn": ["@my-scope/my-shapes:build"],
      ...
    }
  }
}
```

Mô hình của bạn bây giờ có thể tham chiếu các shape của thư viện bằng use:

$version: "2.0"

namespace com.example.api

use com.example.shared#Customer

structure GetCustomerOutput {
    @required
    customer: Customer
}

Các shape library có thể phụ thuộc vào các shape library khác theo cùng một cách. Vì mô hình đã được xây dựng của mỗi thư viện đã chứa các phụ thuộc của chính nó, bạn chỉ cần lặp lại các bước này cho các thư viện mà bạn tham chiếu trực tiếp. Một thư viện được tiếp cận bởi nhiều hơn một đường dẫn chỉ được giải quyết một lần — Smithy bỏ qua các định nghĩa shape trùng lặp nhưng tương đương.