Smithy 프로젝트

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

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

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

팁

구현이 포함된 API를 원한다면 ts#api 생성기를 대신 사용하세요. 이것은 Smithy 모델 프로젝트 와 이를 구현하는 TypeScript 서버를 생성합니다.

사용법

Smithy 프로젝트 생성

VSCode

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

옵션

매개변수	타입	기본값	설명
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 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다). 마지막에 한 번만 설치하세요.

생성기 출력

type = shapes

Shape Library

• 디렉터리my-shapes

  • 디렉터리src

    • main.smithy 공유 shape 정의
  • smithy-build.json Smithy 빌드 구성
  • build.Dockerfile 모델을 빌드하고 검증
  • project.json 프로젝트 구성 및 빌드 타겟

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/model.json에 단일 JSON 모델 파일로 조립합니다.

type = service

Service

• 디렉터리my-service

  • 디렉터리src

    • main.smithy 서비스 정의
    • 디렉터리operations

      • echo.smithy 예제 작업
  • smithy-build.json 코드 생성을 포함한 Smithy 빌드 구성
  • build.Dockerfile 모델, OpenAPI 스펙 및 TypeScript Server SDK를 빌드
  • project.json 프로젝트 구성 및 빌드 타겟

서비스 모델은 서비스 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 프로젝트는 Docker를 사용하여 빌드되며, Smithy CLI를 실행하여 모델을 검증합니다:

pnpm

pnpm nx build my-shapes

yarn

yarn nx build my-shapes

npm

npx nx build my-shapes

bun

bunx nx build my-shapes

Shape Library에 의존하기

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

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

1. Smithy 프로젝트는 컨테이너 내부에서 빌드되며, 빌드에는 작업 공간 루트가 명명된 빌드 컨텍스트로 제공됩니다. 소비 프로젝트의 build.Dockerfile에 자체 소스가 복사되는 위치와 함께 COPY를 추가하세요:

   # 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

2. 소비 프로젝트의 smithy-build.json에서 복사된 파일을 imports에 추가하세요:

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

3. 소비자가 빌드되기 전에 모델이 존재하도록 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 정의를 무시합니다.