image
Akan.js
한국어
문서컨벤션레퍼런스Cheatsheet
image
Akan.js
문서컨벤션레퍼런스Cheatsheet
MIT 라이선스 하에 배포되었습니다.
Akan.js 공식 컨설팅 서비스Akansoft
Copyright © 2026 Akan.js 모든 권리 보유.
시스템 관리자bassman
일반
• 인증
• 스키마 설계
• 엣지 컴퓨팅
• 파일 관리
• Single Sign-On
• DataList & Enum
인터페이스
• CRUD
• Endpoint
• Form
관측성
• 로깅
• 의존성 주입
• 에러 처리
• 메트릭
성능
• 캐싱
• 이미지 최적화
• 지연 로딩
• 쿼리
• 큐
• 실시간
개발
• 문서화
• 스크립트
• 도커
• 쿠버네티스
일반
• 인증
• 스키마 설계
• 엣지 컴퓨팅
• 파일 관리
• Single Sign-On
• DataList & Enum
인터페이스
• CRUD
• Endpoint
• Form
관측성
• 로깅
• 의존성 주입
• 에러 처리
• 메트릭
성능
• 캐싱
• 이미지 최적화
• 지연 로딩
• 쿼리
• 큐
• 실시간
개발
• 문서화
• 스크립트
• 도커
• 쿠버네티스
이전
엣지 컴퓨팅
다음
Single Sign-On

무엇을 만들까

최소 파일 기능의 핵심은 단순합니다. 실제 파일은 저장소에 두고, DB에는 파일을 찾기 위한 기록만 저장합니다.
  • File model은 파일명, URL, 크기, 상태, 진행률을 저장합니다.
  • Upload endpoint는 client에서 `Upload`를 받습니다.
  • Service는 file stream을 저장소에 쓰고 File record를 갱신합니다.
  • 로컬 개발에서는 작은 endpoint가 파일을 stream으로 다시 제공할 수 있습니다.

최소 File 모델

처음에는 UI에 필요한 field만 넣으세요. 이미지 크기, blur preview, 원본 URL 같은 metadata는 나중에 추가해도 됩니다.
file.constant.ts

Upload Endpoint

Endpoint는 단순하게 유지하세요. 파일을 받고, 어떤 용도의 폴더에 넣을지 정한 뒤, 실제 작업은 service에 맡깁니다.
file.signal.ts

File Service

Service가 파일 기능의 중심입니다. 먼저 File record를 만들고, 실제 파일을 업로드한 뒤, 최종 URL을 record에 다시 저장합니다.
  1. `uploading` 상태의 record를 만듭니다.
  2. 파일명 충돌을 피하려고 storage path에 record id를 사용합니다.
  3. 업로드가 끝나면 반환된 URL을 저장하고 상태를 `active`로 바꿉니다.
file.service.ts

로컬 파일 서빙

로컬 저장소가 `/backend/localFile/getBlob/...` 같은 URL을 반환한다면, 파일 stream을 읽어 Response로 돌려주는 작은 endpoint를 추가합니다.
localFile.signal.ts

UI에서 사용하기

업로드 후 UI는 보통 반환된 File record를 사용합니다. 이미지는 `file.url`을 보여주고, 문서는 다운로드 링크로 쓰면 됩니다.
Call fetch.uploadFiles
Preview or download

나중에 확장하기

처음에는 local storage로 시작하세요. 기능이 잘 동작하면 모든 업로드 API를 고치지 말고 storage adapter만 바꿔 S3, R2, MinIO 같은 저장소로 옮기면 됩니다.
  • Local: 디버깅하기 쉽고 개발에 좋습니다.
  • Cloud: 운영 환경과 공유 접근에 좋습니다.
  • Same service: 업로드 로직은 `storageApi` 뒤에 숨겨둡니다.

꿀팁

  • DB record와 실제 파일은 분리하세요. DB는 파일을 찾는 방법을 저장합니다.
  • 서로 같은 이름의 파일을 올려도 충돌하지 않도록 storage path에 File id를 사용하세요.
  • progress는 처음엔 선택 사항이지만, 큰 파일에서는 매우 유용합니다.
  • 파일을 삭제할 때는 File record와 storage object를 함께 정리하세요.
무엇을 만들까
최소 File 모델
Upload Endpoint
File Service
로컬 파일 서빙
UI에서 사용하기
나중에 확장하기
꿀팁