압축 - 🌲 Sonamu

Sonamu는 @fastify/compress를 사용하여 HTTP 응답을 자동으로 압축할 수 있습니다. gzip, deflate, brotli 등 다양한 압축 알고리즘을 지원하며, API별로 압축 여부를 제어할 수 있습니다.

기본 구조

import { defineConfig } from "sonamu";

export default defineConfig({
  server: {
    plugins: {
      compress: {
        global: false, // API별로 제어
        threshold: 1024, // 1KB 이상만 압축
        encodings: ["gzip", "br"], // 지원 알고리즘
      },
    },
  },
  // ...
});

compress 설정

활성화/비활성화

타입: boolean | FastifyCompressOptions

export default defineConfig({
  server: {
    plugins: {
      compress: true, // 기본 설정으로 활성화
    },
  },
});

비활성화:

export default defineConfig({
  server: {
    plugins: {
      compress: false, // 압축 비활성화
    },
  },
});

주요 옵션

global

모든 응답에 자동으로 압축을 적용할지 결정합니다. 타입: boolean 기본값: true

export default defineConfig({
  server: {
    plugins: {
      compress: {
        global: false, // API별로 수동 제어
      },
    },
  },
});

true: 모든 응답을 자동 압축 (기본값)
false: @api({ compress }) 옵션으로 API별 제어

global: false를 권장합니다. 작은 응답이나 이미 압축된 파일(이미지, 동영상)은 압축할 필요가 없기 때문입니다.

threshold

압축을 시작할 최소 응답 크기입니다. 타입: number (bytes) 기본값: 1024 (1KB)

export default defineConfig({
  server: {
    plugins: {
      compress: {
        threshold: 1024, // 1KB 이상만 압축
      },
    },
  },
});

권장값:

1024 (1KB) - 일반적인 웹 앱
512 (512B) - 작은 JSON 응답도 압축
5120 (5KB) - 큰 응답만 압축

너무 작은 응답을 압축하면 오버헤드가 더 클 수 있습니다.

encodings

지원할 압축 알고리즘 목록입니다. 타입: string[] 기본값: ["gzip", "deflate"]

export default defineConfig({
  server: {
    plugins: {
      compress: {
        encodings: ["gzip", "br"], // gzip과 brotli만
      },
    },
  },
});

지원 알고리즘:

"gzip" - 가장 널리 지원됨, 빠른 압축
"deflate" - gzip과 유사
"br" (brotli) - 높은 압축률, 느린 압축

우선순위: 배열 순서대로 클라이언트가 지원하는 첫 번째 알고리즘 사용

Brotli는 압축률이 높지만 CPU를 더 사용합니다. 정적 파일은 미리 압축하고, 동적 응답은 gzip 사용을 권장합니다.

기본 예시

권장 설정

import { defineConfig } from "sonamu";

export default defineConfig({
  server: {
    plugins: {
      compress: {
        global: false, // API별로 제어
        threshold: 1024, // 1KB 이상만
        encodings: ["gzip"], // gzip만 (빠름)
      },
    },
  },
});

Brotli 포함

export default defineConfig({
  server: {
    plugins: {
      compress: {
        global: false,
        threshold: 1024,
        encodings: ["br", "gzip"], // Brotli 우선, gzip 대체
      },
    },
  },
});

자동 압축 (모든 응답)

export default defineConfig({
  server: {
    plugins: {
      compress: {
        global: true, // 모든 응답 자동 압축
        threshold: 512, // 512B 이상
        encodings: ["gzip"],
      },
    },
  },
});

API별 압축 제어

global: false로 설정했다면 @api() 데코레이터의 compress 옵션으로 API별로 압축을 제어할 수 있습니다.

import { api } from "sonamu";

export class DataModel {
  // 압축 적용 (전역 compress 옵션을 그대로 사용)
  @api({ compress: true })
  static async getLargeData() {
    return {
      // 큰 데이터...
    };
  }

  // 압축 안 함 (작은 응답)
  @api()
  static async getSmallData() {
    return { status: "ok" };
  }
}

→ API별 압축 제어 사용법

실전 예시

표준 웹 API

import { defineConfig } from "sonamu";

export default defineConfig({
  server: {
    plugins: {
      compress: {
        global: false, // @api()의 compress 옵션으로 제어
        threshold: 1024, // 1KB 이상만
        encodings: ["gzip"],
      },
    },
  },
});

사용:

export class ArticleModel {
  @api({ compress: true }) // 큰 목록 응답
  static async list() {
    return this.getPuri("r").table("articles").select("*");
  }

  @api({ compress: true }) // 큰 상세 데이터
  static async detail(id: number) {
    return this.findById(id, ["**"]);
  }

  @api() // 작은 응답은 압축 안 함
  static async save(data) {
    return { id: 123 };
  }
}

CDN 최적화

export default defineConfig({
  server: {
    plugins: {
      compress: {
        global: false,
        threshold: 2048, // 2KB 이상만 (CDN 고려)
        encodings: ["br", "gzip"], // Brotli 우선
      },
    },
  },
});

개발 vs 프로덕션

const isDev = process.env.NODE_ENV === "development";

export default defineConfig({
  server: {
    plugins: {
      compress: isDev
        ? false // 개발: 압축 비활성화 (디버깅 편의)
        : {
            global: false,
            threshold: 1024,
            encodings: ["gzip"],
          },
    },
  },
});

고압축률 설정

export default defineConfig({
  server: {
    plugins: {
      compress: {
        global: false,
        threshold: 512, // 작은 응답도 압축
        encodings: ["br"], // Brotli만 (최고 압축률)
        brotliOptions: {
          params: {
            [zlib.constants.BROTLI_PARAM_QUALITY]: 11, // 최대 품질
          },
        },
      },
    },
  },
});

Brotli 품질을 높이면 압축률은 좋아지지만 CPU 사용량이 크게 증가합니다. 프로덕션에서는 테스트 후 사용하세요.

추가 옵션

gzip 레벨

import zlib from "zlib";

export default defineConfig({
  server: {
    plugins: {
      compress: {
        global: false,
        threshold: 1024,
        encodings: ["gzip"],
        zlibOptions: {
          level: zlib.constants.Z_BEST_COMPRESSION, // 최대 압축
        },
      },
    },
  },
});

gzip 레벨:

Z_BEST_SPEED (1) - 빠른 압축
Z_DEFAULT_COMPRESSION (6) - 기본값 (권장)
Z_BEST_COMPRESSION (9) - 최대 압축

특정 Content-Type만 압축

export default defineConfig({
  server: {
    plugins: {
      compress: {
        global: true,
        threshold: 1024,
        encodings: ["gzip"],
        customTypes: /^text\/|json$/, // text/* 와 json만
      },
    },
  },
});

압축 제외

export default defineConfig({
  server: {
    plugins: {
      compress: {
        global: true,
        threshold: 1024,
        encodings: ["gzip"],
        removeContentLengthHeader: false,
        inflateIfDeflated: false,
        onUnsupportedEncoding: (encoding, request, reply) => {
          reply.code(406); // Not Acceptable
          return "Unsupported encoding";
        },
      },
    },
  },
});

압축 확인

응답이 압축되었는지 확인하는 방법:

브라우저 개발자 도구

Network 탭 열기
응답 헤더에서 확인:
Content-Encoding: gzip

Size 확인:

Size: 2.5 KB (transferred)
Size: 10 KB (uncompressed)

curl 테스트

# gzip 압축 요청
curl -H "Accept-Encoding: gzip" http://localhost:34900/api/data -i

# 응답 헤더 확인
# Content-Encoding: gzip
# Content-Length: 1234

# Brotli 압축 요청
curl -H "Accept-Encoding: br" http://localhost:34900/api/data -i

성능 영향

압축의 트레이드오프

장점:

대역폭 절감 (50-80% 감소)
빠른 전송 시간 (특히 느린 네트워크)
CDN 비용 절감

단점:

CPU 사용량 증가
첫 바이트까지 시간 증가 (TTFB)
메모리 사용량 증가

권장 사항

압축해야 하는 것:

JSON 응답 (API)
HTML, CSS, JavaScript
SVG, XML
텍스트 파일

압축하지 말아야 하는 것:

이미지 (JPEG, PNG, WebP) - 이미 압축됨
동영상 (MP4, WebM) - 이미 압축됨
압축 파일 (ZIP, GZ) - 이미 압축됨
매우 작은 응답 (< 1KB)

주의사항

1. 이미 압축된 파일

// ❌ 나쁜 예: 이미지도 압축
compress: {
  global: true,  // 모든 것을 압축
}

// ✅ 좋은 예: API별로 제어
compress: {
  global: false,  // 필요한 것만 @api({ compress: true })
}

2. CPU 사용량

// ❌ 나쁜 예: Brotli 최대 품질
compress: {
  encodings: ["br"],
  brotliOptions: {
    params: {
      [zlib.constants.BROTLI_PARAM_QUALITY]: 11,  // 너무 느림!
    },
  },
}

// ✅ 좋은 예: 적절한 균형
compress: {
  encodings: ["gzip"],  // 빠르고 충분한 압축률
}

3. threshold 설정

// ❌ 나쁜 예: 너무 낮은 threshold
threshold: 100; // 100B - 오버헤드가 더 클 수 있음

// ✅ 좋은 예: 적절한 크기
threshold: 1024; // 1KB

다음 단계

응답 압축 설정을 완료했다면:

compress decorator - API별 압축 제어
cache-control - 캐시와 압축 함께 사용
performance - 성능 최적화

​기본 구조

​compress 설정

​활성화/비활성화

​주요 옵션

​global

​threshold

​encodings

​기본 예시

​권장 설정

​Brotli 포함

​자동 압축 (모든 응답)

​API별 압축 제어

​실전 예시

​표준 웹 API

​CDN 최적화

​개발 vs 프로덕션

​고압축률 설정

​추가 옵션

​gzip 레벨

​특정 Content-Type만 압축

​압축 제외

​압축 확인

​브라우저 개발자 도구

​curl 테스트

​성능 영향

​압축의 트레이드오프

​권장 사항

​주의사항

​1. 이미 압축된 파일

​2. CPU 사용량

​3. threshold 설정

​다음 단계

기본 구조

compress 설정

활성화/비활성화

주요 옵션

global

threshold

encodings

기본 예시

권장 설정

Brotli 포함

자동 압축 (모든 응답)

API별 압축 제어

실전 예시

표준 웹 API

CDN 최적화

개발 vs 프로덕션

고압축률 설정

추가 옵션

gzip 레벨

특정 Content-Type만 압축

압축 제외

압축 확인

브라우저 개발자 도구

curl 테스트

성능 영향

압축의 트레이드오프

권장 사항

주의사항

1. 이미 압축된 파일

2. CPU 사용량

3. threshold 설정

다음 단계