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 thư viện shape với các dự án Smithy của bạn để chia sẻ các shape giữa chúng, thay vì sao chép các định nghĩa trong mỗi dự án.

Cách sử dụng

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

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

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.

Đầu ra của Trình tạo

Thư viện Shape

Thư mụcmy-shapes
- Thư mụcsrc
  - main.smithy Các định nghĩa shape được chia sẻ của bạn
- smithy-build.json Cấu hình build Smithy
- build.Dockerfile Build và xác thực mô hình
- project.json Cấu hình dự án và các target build

Một thư viện shape đị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 thư viện shape 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 build 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/model.json.

Service

Thư mụcmy-service
- Thư mụcsrc
  - main.smithy Định nghĩa dịch vụ của bạn
  - Thư mụcoperations
    echo.smithy Một hoạt động ví dụ
- smithy-build.json Cấu hình build Smithy, bao gồm tạo mã
- build.Dockerfile Build mô hình, đặc tả OpenAPI và TypeScript Server SDK
- project.json Cấu hình dự án và các target build

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 build 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/.

Build

Các dự án Smithy build bằng Docker, chạy Smithy CLI để 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

Phụ thuộc vào một Thư viện Shape

Việc build một thư viện shape ghi một mô hình được tập hợp vào dist/<my-shapes>/build/model/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 một consumer 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 thư viện shape từ một dự án Smithy khác, hãy thực hiện ba thay đổi đối với dự án consumer:

Các dự án Smithy build bên trong một container, và quá trình build được cung cấp workspace root như một build context được đặt tên. Thêm một COPY vào build.Dockerfile của dự án consumer, bên cạnh nơi các nguồn của chính nó được sao chép vào:
```
# Copy project files
COPY smithy-build.json .
COPY src src
COPY --from=workspace dist/packages/my-shapes/build/model/model.json deps/my-shapes.json
```

Thêm tệp đã sao chép vào imports trong smithy-build.json của dự án consumer:

{
  "version": "1.0",
  "sources": ["src/"],
  "imports": ["deps/my-shapes.json"],
  ...
}

Thêm target build của thư viện như một dependency của target compile của dự án consumer trong project.json của nó, để mô hình tồn tại trước khi consumer build:
```
{
  "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 thư viện shape có thể phụ thuộc vào các thư viện shape khác theo cùng một cách. Vì mô hình được build của mỗi thư viện đã chứa các dependency 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 đượ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.