# Node.js Lambda 함수를 위한 계층 작업
<a name="nodejs-layers"></a>

[Lambda 계층](chapter-layers.md)을 사용하여 여러 함수에서 재사용하려는 코드와 종속성을 패키징합니다. 계층에는 일반적으로 라이브러리 종속 항목, [사용자 지정 런타임](runtimes-custom.md) 또는 구성 파일이 포함됩니다. 계층을 생성하려면 세 가지 일반적인 단계를 거칩니다.

1. 계층 콘텐츠를 패키징합니다. 즉, 함수에 사용하려는 종속성이 포함된 .zip 파일 아카이브를 생성합니다.

1. Lambda에서 계층을 생성합니다.

1. 계층을 함수에 추가합니다.

**Topics**
+ [계층 콘텐츠 패키징](#nodejs-layers-package)
+ [Lambda에서 계층 생성](#publishing-layer)
+ [함수에 계층 추가](#nodejs-layer-adding)
+ [샘플 애플리케이션](#nodejs-layer-sample-app)

## 계층 콘텐츠 패키징
<a name="nodejs-layers-package"></a>

계층을 생성하려면 다음 요구 사항을 충족하는 .zip 파일 아카이브로 패키지를 번들링합니다.
+ Lambda 함수에 사용하려는 것과 동일한 Node.js 버전을 사용하여 계층을 빌드합니다. 예를 들어, Node.js 24를 사용하여 계층을 빌드하는 경우 함수에 Node.js 24 런타임을 사용합니다.
+ 계층의 .zip 파일은 다음 디렉터리 구조 중 하나를 사용해야 합니다.
  + `nodejs/node_modules`
  + `nodejs/nodeX/node_modules`(여기서 *X*는 Node.js 버전(예: `node22`))

  자세한 내용은 [각 Lambda 런타임에 대한 계층 경로](packaging-layers.md#packaging-layers-paths) 섹션을 참조하세요.
+ 계층의 패키지는 Linux와 호환되어야 합니다. Lambda 함수는 Amazon Linux에서 실행됩니다.

`npm`을 사용하여 설치한 타사 Node.js 라이브러리(`axios`, `lodash` 등)나 자체 JavaScript 모듈을 포함하는 계층을 생성할 수 있습니다.

### 타사 종속성
<a name="nodejs-layers-third-party-dependencies"></a>

**npm 패키지를 사용하여 계층을 생성하려면 다음을 수행하세요.**

1. 필요한 디렉터리 구조를 생성하고 해당 디렉터리에 패키지를 직접 설치합니다.

   ```
   mkdir -p nodejs
   npm install --prefix nodejs lodash axios
   ```

   이 명령은 Lambda에 필요한 구조인 `nodejs/node_modules` 디렉터리에 패키지를 직접 설치합니다.
**참고**  
네이티브 종속성 또는 바이너리 구성 요소(예: [sharp](https://www.npmjs.com/package/sharp) 또는 [bcrypt](https://www.npmjs.com/package/bcrypt))가 있는 패키지의 경우 Lambda Linux 환경 및 함수의 [아키텍처](foundation-arch.md)와 호환되는지 확인합니다. `--platform` 플래그를 사용해야 할 수 있습니다.  

   ```
   npm install --prefix nodejs --platform=linux --arch=x64 sharp
   ```
보다 복잡한 네이티브 종속성의 경우 Lambda 런타임과 일치하는 Linux 환경에서 컴파일해야 할 수 있습니다. 이 용도로 Docker를 사용할 수 있습니다.

1. 계층 콘텐츠를 .zip 파일로 압축합니다.

------
#### [ Linux/macOS ]

   ```
   zip -r layer.zip nodejs/
   ```

------
#### [ PowerShell ]

   ```
   Compress-Archive -Path .\nodejs -DestinationPath .\layer.zip
   ```

------

   .zip 파일의 디렉터리 구조는 다음과 같아야 합니다.

   ```
   nodejs/
   ├── package.json
   ├── package-lock.json
   └── node_modules/
       ├── lodash/
       ├── axios/
       └── (dependencies of the other packages)
   ```
**참고**  
파일의 루트 수준에 `nodejs` 디렉터리가 포함되어 있고 그 안에 `node_modules`가 있는지 확인하세요. 이 구조는 Lambda가 패키지를 찾아서 가져올 수 있도록 합니다.
`nodejs/` 디렉터리의 `package.json` 및 `package-lock.json` 파일은 npm의 종속성 관리를 위해 사용되지만 Lambda의 계층 기능에는 필요하지 않습니다. 설치된 각 패키지에는 Lambda가 패키지를 가져오는 방식을 정의하는 자체 `package.json` 파일이 이미 포함되어 있습니다.

### 사용자 지정 JavaScript 모듈
<a name="custom-nodejs-modules"></a>

**자체 코드를 사용하여 계층을 생성하려면 다음을 수행하세요.**

1. 계층에 필요한 디렉터리 구조를 생성합니다.

   ```
   mkdir -p nodejs/node_modules/validator
   cd nodejs/node_modules/validator
   ```

1. 사용자 지정 모듈에 대한 `package.json` 파일을 생성하여 해당 모듈을 가져오는 방법을 정의합니다.  
**Example nodejs/node\$1modules/validator/package.json**  

   ```
   {
     "name": "validator",
     "version": "1.0.0",
     "type": "module",
     "main": "index.mjs"
   }
   ```

1. JavaScript 모듈 파일을 생성합니다.  
**Example nodejs/node\$1modules/validator/index.mjs**  

   ```
   export function validateOrder(orderData) {
     // Validates an order and returns formatted data
     const requiredFields = ['productId', 'quantity'];
     
     // Check required fields
     const missingFields = requiredFields.filter(field => !(field in orderData));
     if (missingFields.length > 0) {
       throw new Error(`Missing required fields: ${missingFields.join(', ')}`);
     }
     
     // Validate quantity
     const quantity = orderData.quantity;
     if (!Number.isInteger(quantity) || quantity < 1) {
       throw new Error('Quantity must be a positive integer');
     }
     
     // Format and return the validated data
     return {
       productId: String(orderData.productId),
       quantity: quantity,
       shippingPriority: orderData.priority || 'standard'
     };
   }
   
   export function formatResponse(statusCode, body) {
     // Formats the API response
     return {
       statusCode: statusCode,
       body: JSON.stringify(body)
     };
   }
   ```

1. 계층 콘텐츠를 .zip 파일로 압축합니다.

------
#### [ Linux/macOS ]

   ```
   zip -r layer.zip nodejs/
   ```

------
#### [ PowerShell ]

   ```
   Compress-Archive -Path .\nodejs -DestinationPath .\layer.zip
   ```

------

   .zip 파일의 디렉터리 구조는 다음과 같아야 합니다.

   ```
   nodejs/              
   └── node_modules/
       └── validator/
           ├── package.json
           └── index.mjs
   ```

1. 함수에서 모듈을 가져와서 사용합니다. 예제:

   ```
   import { validateOrder, formatResponse } from 'validator';
   
   export const handler = async (event) => {
     try {
       // Parse the order data from the event body
       const orderData = JSON.parse(event.body || '{}');
       
       // Validate and format the order
       const validatedOrder = validateOrder(orderData);
       
       return formatResponse(200, {
         message: 'Order validated successfully',
         order: validatedOrder
       });
     } catch (error) {
       if (error instanceof Error && error.message.includes('Missing required fields')) {
         return formatResponse(400, {
           error: error.message
         });
       }
       
       return formatResponse(500, {
         error: 'Internal server error'
       });
     }
   };
   ```

   다음 [테스트 이벤트](testing-functions.md#invoke-with-event)를 사용하여 함수를 간접적으로 호출할 수 있습니다.

   ```
   {
       "body": "{\"productId\": \"ABC123\", \"quantity\": 2, \"priority\": \"express\"}"
   }
   ```

   예상 응답:

   ```
   {
     "statusCode": 200,
     "body": "{\"message\":\"Order validated successfully\",\"order\":{\"productId\":\"ABC123\",\"quantity\":2,\"shippingPriority\":\"express\"}}"
   }
   ```

## Lambda에서 계층 생성
<a name="publishing-layer"></a>

AWS CLI 또는 Lambda 콘솔을 사용하여 계층을 게시할 수 있습니다.

------
#### [ AWS CLI ]

[publish-layer-version](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/publish-layer-version.html) AWS CLI 명령을 실행하여 Lambda 계층을 생성합니다.

```
aws lambda publish-layer-version --layer-name my-layer --zip-file fileb://layer.zip --compatible-runtimes nodejs24.x
```

[호환되는 런타임](https://docs.aws.amazon.com/lambda/latest/api/API_PublishLayerVersion.html#lambda-PublishLayerVersion-request-CompatibleRuntimes) 파라미터는 선택 사항입니다. 지정된 경우 Lambda는 이 파라미터를 사용하여 Lambda 콘솔에서 계층을 필터링합니다.

------
#### [ Console ]

**계층을 생성하려면(콘솔)**

1. Lambda 콘솔의 [계층 페이지](https://console.aws.amazon.com/lambda/home#/layers)를 엽니다.

1. **계층 생성**을 선택합니다.

1. **.zip 파일 업로드를** 선택한 다음 이전에 생성한 .zip 아카이브를 업로드합니다.

1. (선택 사항) **호환되는 런타임**에서 계층을 빌드하는 데 사용한 Node.js 버전에 해당하는 Node.js 런타임을 선택합니다.

1. **생성(Create)**을 선택합니다.

------

## 함수에 계층 추가
<a name="nodejs-layer-adding"></a>

------
#### [ AWS CLI ]

함수에 계층을 연결하려면 [update-function-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-configuration.html) AWS CLI 명령을 실행합니다. `--layers` 파라미터의 경우 계층 ARN을 사용합니다. ARN은 버전을 지정해야 합니다(예: `arn:aws:lambda:us-east-1:123456789012:layer:my-layer:1`). 자세한 내용은 [계층 및 계층 버전](chapter-layers.md#lambda-layer-versions) 섹션을 참조하세요.

```
aws lambda update-function-configuration --function-name my-function --cli-binary-format raw-in-base64-out --layers "arn:aws:lambda:us-east-1:123456789012:layer:my-layer:1"
```

**cli-binary-format** 옵션은 AWS CLI 버전 2를 사용할 때 필요합니다. 이 설정을 기본 설정으로 지정하려면 `aws configure set cli-binary-format raw-in-base64-out`을(를) 실행하세요. 자세한 내용은 *AWS Command Line Interface 사용 설명서 버전 2*에서 [AWS CLI 지원 글로벌 명령줄 옵션](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-options.html#cli-configure-options-list)을 참조하세요.

------
#### [ Console ]

**함수에 계층을 추가하려면 다음을 수행하세요.**

1. Lambda 콘솔의 [함수 페이지](https://console.aws.amazon.com/lambda/home#/functions)를 엽니다.

1. 함수를 선택합니다.

1. 아래로 스크롤하여 **계층** 섹션으로 이동하고 **계층 추가**를 선택하세요.

1. **계층 선택**에서 **사용자 지정 계층**을 선택하고 계층을 선택합니다.
**참고**  
계층을 생성할 때 [호환되는 런타임](https://docs.aws.amazon.com/lambda/latest/api/API_PublishLayerVersion.html#lambda-PublishLayerVersion-request-CompatibleRuntimes)을 추가하지 않은 경우 여기에 계층이 나열되지 않습니다. 대신 계층 ARN을 지정할 수 있습니다.

1. **추가**를 선택합니다.

------

## 샘플 애플리케이션
<a name="nodejs-layer-sample-app"></a>

Lambda 계층을 사용하는 방법의 자세한 예는 AWS Lambda Developer Guide GitHub 리포지토리의 [layer-nodejs](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/layer-nodejs) 샘플 애플리케이션을 참조하세요. 이 애플리케이션에는 [lodash](https://www.npmjs.com/package/lodash) 라이브러리가 있는 계층이 포함되어 있습니다. 계층을 생성한 후 해당 함수를 배포하고 간접적으로 호출하여 계층이 예상대로 작동하는지 확인할 수 있습니다.