Smithy 프로젝트

Smithy는 서비스와 서비스가 교환하는 데이터를 설명하기 위한 인터페이스 정의 언어입니다. Smithy 프로젝트 생성기는 Smithy 모델을 포함하는 프로젝트를 생성합니다.

Smithy 프로젝트에는 두 가지 종류가 있습니다:

서비스 (--type=service) — 서비스와 그 작업을 정의하는 모델입니다. 이것은 ts#api --framework=smithy 생성기가 TypeScript 구현과 함께 생성하는 것입니다.
Shape 라이브러리 (--type=shapes) — 재사용 가능한 shape을 정의하지만 서비스는 정의하지 않는 모델입니다. Shape 라이브러리를 Smithy 프로젝트에 연결하여 각 프로젝트에서 정의를 복제하는 대신 프로젝트 간에 shape을 공유할 수 있습니다.

사용법

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

어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

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

설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
VSCode에서 Nx 콘솔 열기
클릭 Generate (UI) "Common Nx Commands" 섹션에서
검색 @aws/nx-plugin - smithy#project
필수 매개변수 입력
- name: my-shapes
클릭 Generate

옵션

매개변수	타입	기본값	설명
name 필수	string	-	Smithy 프로젝트 이름
type	service \| shapes	service	생성할 Smithy 프로젝트의 유형입니다. service(구현 준비가 완료된 서비스 shape가 있는 모델)와 shapes(여러 Smithy 프로젝트 간에 공유되는 재사용 가능한 shape의 라이브러리) 중에서 선택하세요.
serviceName	string	-	Smithy 서비스의 이름입니다. 기본적으로 제공된 이름을 사용합니다. shape 라이브러리에는 적용되지 않습니다.
namespace	string	-	Smithy API의 네임스페이스입니다. 모노레포 스코프가 기본값입니다.
directory	string	packages	Smithy 프로젝트가 배치되는 상위 디렉토리입니다.
subDirectory	string	-	Smithy 프로젝트가 배치되는 하위 디렉토리입니다. 기본적으로 프로젝트 이름입니다.
preferInstallDependencies	boolean	true	생성기 실행 후 의존성 설치를 선호할지 여부입니다. 여러 생성기를 일괄 실행할 때 설치를 연기하려면 false로 설정하세요 (후속 생성기가 Nx 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다). 마지막에 한 번만 설치하세요.

생성기 출력

Shape 라이브러리

디렉터리my-shapes
- 디렉터리src
  - main.smithy Your shared shape definitions
- smithy-build.json Smithy build configuration
- project.json Project configuration and build targets

Shape 라이브러리는 shape만 정의합니다:

$version: "2.0"

namespace com.example

structure Customer {
    @required
    id: String

    name: String
    email: String
}

Shape 라이브러리에는 서비스가 없으므로 smithy-build.json은 코드 생성을 구성하지 않습니다 — 빌드하면 모델을 검증하고 dist/<my-shapes>/build/model.json에 단일 JSON 모델 파일로 조립합니다.

서비스

디렉터리my-service
- 디렉터리src
  - main.smithy Your service definition
  - 디렉터리operations
    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

서비스 모델은 서비스 shape과 노출하는 작업을 정의합니다:

$version: "2.0"

namespace com.example

use aws.protocols#restJson1

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

서비스 프로젝트를 빌드하면 OpenAPI 사양과 TypeScript Server SDK가 dist/<my-service>/build/에 생성됩니다.

빌드

Smithy 프로젝트는 모델을 검증하는 Smithy CLI로 빌드됩니다:

pnpm nx build my-shapes

yarn nx build my-shapes

npx nx build my-shapes

bunx nx build my-shapes

macOS와 Linux에서는 CLI가 mise에 의해 해결되며, 빌드가 필요에 따라 가져오므로 설치할 것이 없습니다 — 처음 빌드할 때 고정된 버전을 다운로드하고 캐시합니다. Windows에서는 직접 설치해야 하는 전제 조건입니다 — Windows에서 빌드하기를 참조하세요.

Shape 라이브러리에 의존하기

Shape 라이브러리를 빌드하면 조립된 모델이 dist/<my-shapes>/build/model.json에 작성됩니다. 이 단일 파일에는 라이브러리가 정의하는 모든 shape과 의존하는 모든 shape이 포함되어 있으므로 소비자는 직접 참조하는 라이브러리만 선언하면 됩니다.

다른 Smithy 프로젝트에서 shape 라이브러리에 의존하려면 소비하는 프로젝트에 두 가지 변경을 수행하세요:

소비하는 프로젝트의 smithy-build.json의 imports에 라이브러리의 빌드된 모델을 추가합니다. 경로는 해당 파일을 기준으로 상대적이므로 ../ 세그먼트의 수는 소비하는 프로젝트가 중첩된 깊이와 일치합니다 — 아래 packages/my-api/model의 경우 세 개입니다:
```
{
  "version": "1.0",
  "sources": ["src/"],
  "imports": ["../../../dist/packages/my-shapes/build/model.json"],
  ...
}
```
소비하는 프로젝트가 빌드되기 전에 모델이 존재하도록 project.json의 소비하는 프로젝트의 compile 타겟의 의존성으로 라이브러리의 build 타겟을 추가합니다:
```
{
  "targets": {
    "compile": {
      "dependsOn": ["@my-scope/my-shapes:build"],
      ...
    }
  }
}
```

이제 모델에서 use를 사용하여 라이브러리의 shape을 참조할 수 있습니다:

$version: "2.0"

namespace com.example.api

use com.example.shared#Customer

structure GetCustomerOutput {
    @required
    customer: Customer
}

Shape 라이브러리는 같은 방식으로 다른 shape 라이브러리에 의존할 수 있습니다. 각 라이브러리의 빌드된 모델에는 이미 자체 의존성이 포함되어 있으므로 직접 참조하는 라이브러리에 대해서만 이러한 단계를 반복하면 됩니다. 둘 이상의 경로로 도달하는 라이브러리는 한 번만 해결됩니다 — Smithy는 중복되지만 동등한 shape 정의를 무시합니다.