From db06c95724fb51a38755bbc67246232cf58168d3 Mon Sep 17 00:00:00 2001 From: johngreen Date: Fri, 1 May 2026 21:46:24 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20REST=20API=20=EC=95=84=ED=82=A4?= =?UTF-8?q?=ED=85=8D=EC=B2=98=20=EB=AC=B8=EC=84=9C=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit backend-architecture-summary.md 는 옛 Node 백엔드(VEX 1세대) 기준이라 현재 Spring 백엔드의 컨벤션이 문서화돼있지 않음. 신규 작업자가 합의된 패턴(3-layer, Map, 네이밍 규칙, 표준 응답, common SQL 단편) 을 한 곳에서 빠르게 파악할 수 있게 정리. 다른 아키텍처 문서(MULTI_TENANCY_ARCHITECTURE / DOMAIN_MAPPING) 와 상호 링크. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/REST_API_ARCHITECTURE.md | 213 ++++++++++++++++++++++++++++++++++ 1 file changed, 213 insertions(+) create mode 100644 docs/REST_API_ARCHITECTURE.md diff --git a/docs/REST_API_ARCHITECTURE.md b/docs/REST_API_ARCHITECTURE.md new file mode 100644 index 00000000..c9847a62 --- /dev/null +++ b/docs/REST_API_ARCHITECTURE.md @@ -0,0 +1,213 @@ +# INVYONE REST API 아키텍처 + +> **3-layer (Controller → Service → XML), DTO 없음, Map 일원화.** +> 로우코드 ERP 특성상 테이블/컬럼이 런타임에 결정되므로 사전 정의 DTO를 두지 않고 모든 데이터를 키-값 맵으로 흘린다. + +--- + +## 1. 기술 스택 + +``` +언어 Java 21 +프레임워크 Spring Boot 3.x +DB 접근 MyBatis (XML) + sqlSession 직접 호출 +DB PostgreSQL 16 (DB-per-tenant) +인증 JWT (Authorization: Bearer …) +빌드 Gradle 8.10 +``` + +멀티테넌시·서브도메인 라우팅은 별도 문서: [`MULTI_TENANCY_ARCHITECTURE.md`](./MULTI_TENANCY_ARCHITECTURE.md). + +--- + +## 2. 3-layer 구조 + +``` +[HTTP 요청] + ↓ +@RestController ← 입력 추출, 검증, 응답 래핑 + ↓ Map +Service extends BaseService ← 비즈니스 로직, sqlSession 호출 + ↓ namespace.queryId +mapper/{module}.xml ← SQL (UPPER_SNAKE), 동적 OGNL + ↓ +PostgreSQL (테넌트 자동 라우팅) +``` + +### 절대 규칙 + +- **`@Mapper` 인터페이스 만들지 않는다.** Service 가 `sqlSession.selectList("namespace.queryId", params)` 직접 호출. +- **DTO·엔티티 클래스 만들지 않는다.** 파라미터·응답 모두 `Map` 또는 `List>`. +- **유일한 DTO는 `ApiResponse`** (성공/실패 + payload 래퍼). +- **Service 는 반드시 `BaseService` 상속** + `@Slf4j` + `@Autowired CommonService`. + +--- + +## 3. 네이밍 컨벤션 (전 영역 일관) + +| 위치 | 컨벤션 | 예 | +|---|---|---| +| Java 코드 (변수/메서드/클래스) | `camelCase` | `getOrderList()`, `String companyCode` | +| Map 키 (`params.put`, `row.get`) | `snake_case` | `params.put("company_code", ...)` | +| MyBatis `#{파라미터}` | `snake_case` | `#{company_code}`, `#{table_name}` | +| SQL 키워드/테이블/컬럼 | `UPPER_SNAKE` | `SELECT COMPANY_CODE FROM TEMPLATES` | +| SELECT 쉼표 | 앞에 | `, COLUMN_NAME` | +| XML 파일명 | 소문자, `Mapper` 접미사 없음 | `meta.xml`, `template.xml` | +| XML namespace | 파일명과 동일 | `namespace="meta"` | +| OGNL `test` 속성 | 바깥 작은따옴표 | `test='company_code != "*"'` | + +> **Java는 camelCase, DB·맵은 snake_case.** 경계는 Service 안에서만 발생 — Controller·XML 내부엔 변환 코드 없음. + +--- + +## 4. 메서드·엔드포인트 패턴 + +| 조작 | 메서드명 | HTTP | +|---|---|---| +| 목록 | `get{Module}List` | `GET /api/{module}/list` | +| 카운트 | `get{Module}ListCnt` | `GET /api/{module}/list/count` | +| 단건 | `get{Module}Info` | `GET /api/{module}/{id}` | +| 등록 | `insert{Module}` | `POST /api/{module}` | +| 수정 | `update{Module}` | `PUT /api/{module}/{id}` | +| 삭제 | `delete{Module}` | `DELETE /api/{module}/{id}` | + +**List API는 반드시 Count 쿼리를 동반한다.** `getXxxList` + `getXxxListCnt` 한 세트로 페이지네이션을 보장. + +--- + +## 5. 표준 응답 (`ApiResponse`) + +```java +// 성공 +ResponseEntity.ok(ApiResponse.success(data)); +ResponseEntity.ok(ApiResponse.success(data, "메시지")); + +// 실패 +ResponseEntity.badRequest().body(ApiResponse.error("사용자 ID와 비밀번호를 입력해주세요.")); +``` + +JSON: +```json +{ + "success": true, + "message": "조회 완료", + "data": [...] +} +``` + +프론트는 항상 `success` + `data`만 보면 충분. + +--- + +## 6. `common` 레이어 (공용 SQL 조각) + +`mapper/common.xml` 의 `` 단편을 모든 모듈에서 ``. + +```xml + +``` + +- `companyCodeFilter` — 멀티 회사 데이터 분리 (`COMPANY_CODE = #{company_code}`). +- `dynamicOrderBy` — 프론트에서 받은 정렬 필드/방향 동적 적용. +- `pagination` — `LIMIT #{page_size} OFFSET #{offset}`. + +--- + +## 7. 인증 (JWT) + +- 로그인: `POST /api/auth/login` body `{ "user_id": "...", "password": "..." }`. +- 응답에 `access_token` 포함. 이후 요청은 `Authorization: Bearer {token}` 헤더 필수. +- 검증은 `JwtAuthenticationFilter` 가 일괄. 토큰 페이로드의 `company_code`·`user_id`·`role` 이 `SecurityContext` 로 흐름. +- `SubdomainResolverFilter` 다음에 동작 → 테넌트 컨텍스트 + 사용자 컨텍스트 모두 갖춘 채 컨트롤러 진입. + +화이트리스트(공개 엔드포인트): `/api/auth/login`, `/api/auth/refresh`, 정적 리소스. + +--- + +## 8. 예시: 템플릿 목록 조회 + +### 컨트롤러 +```java +@RestController +@RequestMapping("/api/template") +@RequiredArgsConstructor +public class TemplateController { + private final TemplateService templateService; + + @GetMapping("/list") + public ResponseEntity getTemplateList(@RequestParam Map params) { + return ResponseEntity.ok(ApiResponse.success(templateService.getTemplateList(params))); + } +} +``` + +### 서비스 +```java +@Service +@Slf4j +public class TemplateService extends BaseService { + @Autowired CommonService commonService; + + public Map getTemplateList(Map params) { + params.put("company_code", currentCompanyCode()); // BaseService 헬퍼 + List> list = sqlSession.selectList("template.getTemplateList", params); + Integer total = sqlSession.selectOne("template.getTemplateListCnt", params); + return Map.of("list", list, "total", total); + } +} +``` + +### 매퍼 (`resources/mapper/template.xml`) +```xml + + + + + +``` + +--- + +## 9. 프론트 연동 (요약) + +- 호출은 항상 `frontend/lib/api/client.ts` (axios 래퍼) 또는 모듈별 클라이언트 (`flow.ts`, `dashboard.ts` 등). `fetch` 직접 사용 금지. +- 응답 타입은 별도 인터페이스 정의 없이 `Record` 사용. (예외: `frontend/types/invyone-component.ts` 의 시스템 핵심 계약 타입만 명시 정의.) +- 베이스 URL 분기 (`*.invyone.com` ↔ `localhost`) 는 클라이언트가 호스트 헤더 보고 알아서 해결 → 컴포넌트는 상대경로만 신경 쓰면 됨. + +--- + +## 10. 관련 문서 + +- [`MULTI_TENANCY_ARCHITECTURE.md`](./MULTI_TENANCY_ARCHITECTURE.md) — 서브도메인 라우팅, DB-per-tenant, 회사 프로비저닝 흐름. +- [`DOMAIN_MAPPING.md`](./DOMAIN_MAPPING.md) — 환경별 도메인·포트. +- `notes/gbpark/2026-04-08-lowcode-platform-spec.md` — 플랫폼 SPEC (왜 DTO를 두지 않는지의 배경).