chore(release): dev 변경사항 main 반영 및 Worker ASG 분리 배포 검증

.env.example

@@ -6,7 +6,16 @@ DB_PASSWORD=
 MYSQL_ROOT_PASSWORD=
 REDIS_HOST=
 REDIS_PORT=
+
 JWT_SECRET=
+
 AWS_S3_BUCKET=
 AWS_ACCESS_KEY_ID=
-AWS_SECRET_ACCESS_KEY=
+AWS_SECRET_ACCESS_KEY=
+AWS_CLOUDFRONT_DOMAIN=
+
+AWS_SQS_ORDER_QUEUE_URL=
+AWS_SQS_CONSUMER_ENABLED=
+
+DOCS_AUTH_USERNAME=
+DOCS_AUTH_PASSWORD=

.github/workflows/ci-cd.yml

@@ -102,6 +102,20 @@ jobs:
     needs: publish
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        target:
+          - name: API
+            launch_template_id: ${{ vars.API_LAUNCH_TEMPLATE_ID }}
+            asg_name: ${{ vars.API_ASG_NAME }}
+            consumer_enabled: 'false'
+          - name: Worker
+            launch_template_id: ${{ vars.WORKER_LAUNCH_TEMPLATE_ID }}
+            asg_name: ${{ vars.WORKER_ASG_NAME }}
+            consumer_enabled: 'true'
+
+    name: Deploy ${{ matrix.target.name }}
 
     steps:
       # Step 1: AWS 자격증명 - OIDC
@@ -112,17 +126,18 @@ jobs:
           aws-region: ${{ vars.AWS_REGION }}
 
       # Step 2: Launch Template 새 버전 생성 (User Data의 IMAGE_TAG를 새 커밋 SHA로 교체)
-      - name: Update Launch Template
+      - name: Update ${{ matrix.target.name }} Launch Template
         env:
           IMAGE_TAG: ${{ needs.publish.outputs.image_tag }}
           AWS_ACCOUNT_ID: ${{ vars.AWS_ACCOUNT_ID }}
           AWS_REGION: ${{ vars.AWS_REGION }}
           ECR_REPOSITORY: ${{ vars.ECR_REPOSITORY }}
-          LAUNCH_TEMPLATE_ID: ${{ vars.LAUNCH_TEMPLATE_ID }}
+          LAUNCH_TEMPLATE_ID: ${{ matrix.target.launch_template_id }}
+          CONSUMER_ENABLED: ${{ matrix.target.consumer_enabled }}
         run: |
           ECR_URI="${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/${ECR_REPOSITORY}"
 
-          USER_DATA=$(cat <<'USERDATA' | sed "s|__IMAGE_TAG__|${IMAGE_TAG}|g; s|__AWS_ACCOUNT_ID__|${AWS_ACCOUNT_ID}|g; s|__AWS_REGION__|${AWS_REGION}|g; s|__ECR_REPOSITORY__|${ECR_REPOSITORY}|g" | base64 -w 0
+          USER_DATA=$(cat <<'USERDATA' | sed "s|__IMAGE_TAG__|${IMAGE_TAG}|g; s|__AWS_ACCOUNT_ID__|${AWS_ACCOUNT_ID}|g; s|__AWS_REGION__|${AWS_REGION}|g; s|__ECR_REPOSITORY__|${ECR_REPOSITORY}|g; s|__CONSUMER_ENABLED__|${CONSUMER_ENABLED}|g" | base64 -w 0
           #!/bin/bash
           set -e
           AWS_REGION="__AWS_REGION__"
@@ -136,7 +151,10 @@ jobs:
           systemctl start docker
           aws ecr get-login-password --region ${AWS_REGION} | docker login --username AWS --password-stdin ${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com
           docker pull ${ECR_URI}:${IMAGE_TAG}
-          docker run -d -p 8080:8080 --restart unless-stopped --name ci-demo -e SPRING_PROFILES_ACTIVE=prod ${ECR_URI}:${IMAGE_TAG}
+          docker run -d -p 8080:8080 --restart unless-stopped --name ci-demo \
+            -e SPRING_PROFILES_ACTIVE=prod \
+            -e AWS_SQS_CONSUMER_ENABLED=__CONSUMER_ENABLED__ \
+            ${ECR_URI}:${IMAGE_TAG}
           USERDATA
           )
 
@@ -156,10 +174,10 @@ jobs:
           echo "✅ 기본 버전 → v${NEW_VERSION} 변경 완료"
 
       # Step 3: Instance Refresh 시작
-      - name: Start Instance Refresh
+      - name: Start ${{ matrix.target.name }} Instance Refresh
         id: refresh
         env:
-          ASG_NAME: ${{ vars.ASG_NAME }}
+          ASG_NAME: ${{ matrix.target.asg_name }}
         run: |
           REFRESH_ID=$(aws autoscaling start-instance-refresh \
             --auto-scaling-group-name ${ASG_NAME} \
@@ -174,9 +192,9 @@ jobs:
           echo "✅ Instance Refresh 시작: ${REFRESH_ID}"
 
       # Step 4: Instance Refresh 완료 대기
-      - name: Wait for Instance Refresh
+      - name: Wait for ${{ matrix.target.name }} Instance Refresh
         env:
-          ASG_NAME: ${{ vars.ASG_NAME }}
+          ASG_NAME: ${{ matrix.target.asg_name }}
           REFRESH_ID: ${{ steps.refresh.outputs.refresh_id }}
         run: |
           echo "⏳ Instance Refresh 완료 대기 중..."

.gitignore

@@ -42,3 +42,5 @@ out/
 !.env.example
 !.env.example.DS_Store
 performance/reports/*.html
+performance/results/raw/
+performance/results/*.zip

README.md

@@ -102,9 +102,23 @@ src/main/java/com/dropit
 
 ## API 문서
 
-<!-- 예시: [Postman API Documentation](https://documenter.getpostman.com/view/...) -->
+Spring REST Docs를 사용하고, 테스트 스니펫을 OpenAPI 3.0.1 명세로 변환합니다.
+Swagger UI는 이 명세 파일을 읽어 화면에 보여주는 역할만 하므로, 별도의 어노테이션 기반 API 명세가 생기지 않습니다.
 
-_링크 추가 예정_
+`bootRun`과 `bootJar`는 테스트와 OpenAPI 생성 작업을 먼저 실행한 뒤 생성된 YAML을 애플리케이션 정적 리소스에 포함합니다.
+명세와 Swagger UI 리소스를 단독으로 준비하려면 `./gradlew openApiDocs`를 실행합니다.
+명세만 생성하려면 `./gradlew openapi3`를 실행하며, 결과는 `build/api-spec/openapi3.yaml`에 저장됩니다. (생성물은 빌드 디렉터리에만 남으며 저장소에는 커밋하지 않습니다.)
+
+브라우저에서 http://localhost:8080/swagger-ui/index.html를 열면 API 문서를 확인할 수 있습니다.
+원본 명세는 http://localhost:8080/openapi/openapi3.yaml 경로에서도 직접 확인할 수 있습니다.
+
+Swagger UI와 OpenAPI YAML은 HTTP Basic Auth로 보호됩니다.
+로컬에서는 `.env.local`에 다음 두 값을 설정합니다.
+
+```properties
+DOCS_AUTH_USERNAME=<local username>
+DOCS_AUTH_PASSWORD=<local password>
+```
 
 인증이 필요한 API는 다음 헤더를 전달합니다.
 

build.gradle

@@ -2,13 +2,15 @@ plugins {
     id 'java'
     id 'org.springframework.boot' version '4.1.1'
     id 'io.spring.dependency-management' version '1.1.7'
+    id 'com.epages.restdocs-api-spec' version '0.20.1'
 }
 
 group = 'com.dropit'
 version = '0.0.1-SNAPSHOT'
 description = 'dropit-server'
 
 def querydslVersion = '7.5'
+def restdocsApiSpecVersion = '0.20.1'
 
 java {
     toolchain {
@@ -28,10 +30,13 @@ dependencies {
     implementation "io.github.openfeign.querydsl:querydsl-jpa:${querydslVersion}"
     implementation 'org.springframework.boot:spring-boot-starter-security'
     implementation 'org.springframework.boot:spring-boot-starter-actuator'
+    implementation 'org.webjars:swagger-ui:5.32.11'
 
     implementation platform('io.awspring.cloud:spring-cloud-aws-dependencies:4.1.0')
     implementation 'io.awspring.cloud:spring-cloud-aws-starter-parameter-store'
     implementation 'io.awspring.cloud:spring-cloud-aws-starter-s3'
+    implementation 'io.awspring.cloud:spring-cloud-aws-starter-sqs'
+    implementation 'software.amazon.awssdk:url-connection-client'
 
     implementation 'io.jsonwebtoken:jjwt-api:0.13.0'
     runtimeOnly 'io.jsonwebtoken:jjwt-impl:0.13.0'
@@ -51,13 +56,111 @@ dependencies {
     testImplementation 'org.springframework.boot:spring-boot-starter-actuator-test'
     testImplementation 'org.testcontainers:testcontainers-mysql'
 
+    testImplementation platform('org.springframework.restdocs:spring-restdocs-bom:4.0.1')
+    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
+    testImplementation "com.epages:restdocs-api-spec-mockmvc:${restdocsApiSpecVersion}"
+
     testCompileOnly 'org.projectlombok:lombok'
     testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
     testAnnotationProcessor 'org.projectlombok:lombok'
 }
 
 tasks.named('test') {
     useJUnitPlatform()
+    outputs.dir(file('build/generated-snippets'))
+}
+
+openapi3 {
+    server = '/'
+    title = 'DROPIT API'
+    description = 'DROPIT API 문서입니다.'
+    version = project.version.toString()
+    format = 'yaml'
+    outputDirectory = 'build/api-spec'
+}
+
+afterEvaluate {
+    tasks.named('openapi3') {
+        dependsOn(tasks.named('test'))
+        doLast {
+            File specFile = layout.buildDirectory.file('api-spec/openapi3.yaml').get().asFile
+            String spec = specFile.getText('UTF-8')
+
+            // restdocs-api-spec models a primitive JSON response as an empty object because
+            // its field-descriptor schema generator only supports object/array roots. Keep
+            // the endpoint contract accurate for the two Long response endpoints.
+            [
+                    [path: '/drops', method: 'post', status: '201'],
+                    [path: '/products', method: 'post', status: '201']
+            ].each { endpoint ->
+                String pattern = /(?s)(\x20{2}${endpoint.path}:.*?\x20{4}${endpoint.method}:.*?responses:\n\x20{8}"${endpoint.status}":.*?application\/json:\n\x20{14}schema:\n)\x20{16}[$]ref: "[^"]+"\n/
+                spec = spec.replaceFirst(pattern, '$1                type: integer\n                format: int64\n')
+            }
+
+            // Primitive response correction leaves the generator's orphaned hash schema behind.
+            // Remove only those generated hash components; domain schema names come from tests.
+            spec = spec.replaceAll(
+                    /(?ms)^\x20{4}[A-Za-z0-9]+-\d+:\n.*?(?=^\x20{4}[A-Za-z0-9]+:|^\x20{2}securitySchemes:)/,
+                    ''
+            )
+
+            String multipartSchema =
+                    /(?s)(\x20{4}MultipartImage:\n)(?:\x20{6}title: MultipartImage\n)?\x20{6}type: object\n/
+            spec = spec.replaceFirst(
+                    multipartSchema,
+                    '$1      required:\n      - file\n      type: object\n      properties:\n        file:\n          type: string\n          format: binary\n'
+            )
+
+            specFile.setText(spec, 'UTF-8')
+        }
+    }
+}
+
+def validateOpenApiSpec = tasks.register('validateOpenApiSpec') {
+    group = 'documentation'
+    description = '생성된 OpenAPI 명세가 하나 이상의 API 경로를 포함하는지 검증합니다.'
+    dependsOn(tasks.named('openapi3'))
+    doLast {
+        File specFile = layout.buildDirectory.file('api-spec/openapi3.yaml').get().asFile
+        if (!specFile.isFile() || specFile.length() == 0) {
+            throw new GradleException(
+                    "OpenAPI 명세가 생성되지 않았습니다: ${specFile}. ./gradlew openapi3을 실행해 문서화 테스트를 먼저 수행하세요."
+            )
+        }
+
+        String spec = specFile.getText('UTF-8')
+        boolean hasPathsSection = spec.readLines().any { it.trim() == 'paths:' }
+        boolean hasDocumentedPath = spec.readLines().any { it ==~ /^\s{2,}\/\S+:\s*$/ }
+        if (!hasPathsSection || !hasDocumentedPath) {
+            throw new GradleException(
+                    "OpenAPI 명세에 문서화된 API 경로가 없습니다: ${specFile}. -x test를 사용하지 말고 ./gradlew openapi3을 실행하세요."
+            )
+        }
+    }
+}
+
+def copyOpenApiToResources = tasks.register('copyOpenApiToResources', Copy) {
+    dependsOn(validateOpenApiSpec)
+    from(layout.buildDirectory.file('api-spec/openapi3.yaml'))
+    into(layout.buildDirectory.dir('resources/main/static/openapi'))
+}
+
+tasks.named('bootRun') {
+    dependsOn(copyOpenApiToResources)
+}
+
+tasks.named('resolveMainClassName') {
+    dependsOn(copyOpenApiToResources)
+}
+
+tasks.named('bootJar') {
+    dependsOn(copyOpenApiToResources)
+}
+
+tasks.register('openApiDocs') {
+    group = 'development'
+    description = 'OpenAPI 명세를 생성하고 검증한 뒤 정적 리소스로 복사합니다.'
+    dependsOn(copyOpenApiToResources)
 }
 
 tasks.register('dbUp', Exec) {
@@ -71,3 +174,42 @@ tasks.register('dbDown', Exec) {
     description = '로컬 DB 컨테이너를 종료합니다.'
     commandLine 'docker', 'compose', '--env-file', '.env.local', 'down'
 }
+
+def performanceComposeFile = file('performance/compose.performance.yml')
+def performanceRawResultDirectory = file('performance/results/raw')
+
+tasks.register('performanceUp', Exec) {
+    group = 'verification'
+    description = '성능 관측용 InfluxDB와 Grafana를 실행합니다.'
+    commandLine 'docker', 'compose', '--file', performanceComposeFile,
+            'up', '--detach', '--wait', 'influxdb', 'grafana'
+}
+
+tasks.register('performanceSmoke', Exec) {
+    group = 'verification'
+    description = 'k6가 성능 관측 스택에 지표와 JSON 결과를 기록하는지 확인합니다.'
+    dependsOn(tasks.named('performanceUp'))
+
+    doFirst {
+        performanceRawResultDirectory.mkdirs()
+    }
+
+    environment 'BASE_URL', 'http://influxdb:8086'
+    environment 'TEST_RUN', 'performance-stack-smoke'
+    environment 'K6_SCRIPT', 'performance-stack-smoke.js'
+    commandLine 'docker', 'compose', '--file', performanceComposeFile,
+            '--profile', 'load', 'run', '--rm', 'k6'
+
+    doLast {
+        File summary = new File(performanceRawResultDirectory, 'performance-stack-smoke.json')
+        if (!summary.isFile() || summary.length() == 0) {
+            throw new GradleException("k6 smoke 결과가 생성되지 않았습니다: ${summary}")
+        }
+    }
+}
+
+tasks.register('performanceDown', Exec) {
+    group = 'verification'
+    description = '성능 관측용 컨테이너와 네트워크를 종료합니다.'
+    commandLine 'docker', 'compose', '--file', performanceComposeFile, 'down'
+}

performance/compose.performance.yml

@@ -0,0 +1,59 @@
+name: dropit-performance
+
+services:
+  influxdb:
+    image: influxdb:1.8.10
+    environment:
+      INFLUXDB_DB: k6
+    ports:
+      - "127.0.0.1:8086:8086"
+    volumes:
+      - influxdb-data:/var/lib/influxdb
+    healthcheck:
+      test: ["CMD", "curl", "--fail", "http://localhost:8086/ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+
+  grafana:
+    image: grafana/grafana:12.4.10
+    environment:
+      GF_AUTH_ANONYMOUS_ENABLED: "true"
+      GF_AUTH_ANONYMOUS_ORG_ROLE: Viewer
+      GF_USERS_DEFAULT_THEME: light
+    ports:
+      - "127.0.0.1:3000:3000"
+    volumes:
+      - grafana-data:/var/lib/grafana
+      - ./grafana/provisioning:/etc/grafana/provisioning:ro
+      - ./grafana/dashboards:/var/lib/grafana/dashboards:ro
+    depends_on:
+      influxdb:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "wget", "--spider", "-q", "http://localhost:3000/api/health"]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+
+  k6:
+    image: grafana/k6:1.7.1
+    profiles: ["load"]
+    environment:
+      K6_OUT: influxdb=http://influxdb:8086/k6
+      BASE_URL: ${BASE_URL:-http://host.docker.internal:8080}
+      TEST_RUN: ${TEST_RUN:-order-flow-smoke}
+      AUTH_TOKEN: ${AUTH_TOKEN:-}
+    volumes:
+      - ./k6:/scripts:ro
+      - ./results/raw:/results
+    depends_on:
+      influxdb:
+        condition: service_healthy
+    entrypoint: ["k6"]
+    command: ["run", "/scripts/${K6_SCRIPT:-drop-list-index.js}"]
+    restart: "no"
+
+volumes:
+  influxdb-data:
+  grafana-data: