🍏 SQL UnvUs Style Convention

가독성 높은 SQL 작성을 위한 UnvUs 스타일 가이드

✨ 개요 (Overview)

SQL은 단순한 데이터 질의 언어가 아닙니다. 우리가 작성하는 쿼리도 하나의 디자인이며, 그 디자인이 명확하고 흐름이 있어야 데이터도 아름답게 다가옵니다.

UnvUs스럽고 직관적인 쿼리 작성을 위한 UnvUs Style SQL Convention을 소개합니다.

이 규칙이 적용되는 범위

현재 대부분의 쿼리는 Java DSL 로 작성하고, XML 에는 resultMap 만 남깁니다 (→ MyBatis Dynamic SQL).

• XML 에 남은 SQL — 이 문서의 River Style 을 따릅니다
• Java DSL — 같은 정신(키워드 정렬)을 코드에 적용하고, IDE 자동 포맷이 망가뜨리지 않도록 //@formatter:off … //@formatter:on 으로 감쌉니다

//@formatter:off
return select(b.allColumns())
         .from(b, b.getAlias())
        .where(b.enabled, isTrue())
          .and(b.name, isLike(keyword))
     .orderBy(b.desc(b.createdDt))
        .build().render(RenderingStrategies.MYBATIS3);
//@formatter:on

${} 문자열 치환은 금지입니다

${whereClause} / ${sortBy} 같은 토큰은 값이 SQL 에 그대로 박혀 인젝션 경로가 됩니다. 테스트가 mapper XML 에 이런 토큰이 들어오는 것을 자동으로 막습니다. 동적 조건은 #{} 바인딩과 명시적 <if>, 또는 Java DSL 로 작성하세요.

🌊 UnvUs Style 이란?

INFO

• River Style (강물 스타일): SQL 키워드와 절을 마치 강물이 흐르듯이 정렬하여, 가독성과 논리 구조를 극대화하는 스타일입니다.
• UnvUs Style: River Style의 핵심 원칙을 기반으로, 특히 MyBatis 환경에서의 적용성과 가독성을 더욱 향상시키기 위해 몇 가지 규칙을 재정의하고 구체화한 스타일입니다. (예: <include> 태그 처리, 동적 SQL과의 조화 등)

📌 왼쪽 정렬 키워드 (Main Flow)	📎 오른쪽 정렬 키워드 (조건/수식 등)
SELECT	AS
INSERT / DELETE / UPDATE	IN, IS, LIKE, BETWEEN, EXISTS, DISTINCT
FROM	TRUE / FALSE, NULL, NOT
JOIN, LEFT JOIN, ON	ALL, ANY
WHERE
AND / OR
GROUP BY
HAVING
ORDER BY
LIMIT, OFFSET
UNION, CASE, WHEN, THEN, ELSE, END

---

📐 스타일 가이드라인

✅ 기본 구조

SELECT u.username
     , u.email
     , u.user_id
  FROM users AS u
 WHERE u.is_active = TRUE
 ORDER BY u.username ASC;

• 주요 키워드는 새 줄에서 시작하며 왼쪽 정렬합니다.
• 선택 컬럼, WHERE 절 내부 조건 등은 한 단계 들여쓰기합니다.
• AS, 할당(=), 비교 연산자 (>=, <=, LIKE 등)는 같은 줄에서 자연스럽게 이어지도록 합니다.

---

🤝 JOIN 구조

    SELECT o.order_id
         , o.order_date
         , u.username
         , u.email
      FROM orders AS o
      JOIN users AS u
        ON o.user_id = u.user_id
 LEFT JOIN user_profiles AS p  -- LEFT JOIN도 JOIN과 동일한 라인에 정렬
        ON u.user_id = p.user_id   -- ON 절은 JOIN에 맞춰 들여쓰기
       AND p.is_primary = TRUE     -- ON 절에 여러 조건이 올 경우 AND로 연결
     WHERE u.is_active = TRUE;

• JOIN과 ON은 한 세트로,
• JOIN → ON 순서로 들여쓰기하여 관계를 시각
• LEFT JOIN 의 경우 JOIN 까지가 river

🧩 서브쿼리 (Subquery) 작성 방식

( 괄호는 새로운 리버(River)의 시작점입니다. 서브쿼리 내부도 리버 스타일을 그대로 유지합니다.

✅ 예시

SELECT u.username
     , u.email
     , u.user_id
  FROM users AS u
 WHERE u.user_id IN
       (SELECT o.user_id
          FROM orders AS o
         WHERE o.order_date >= '2024-01-01'
           AND o.order_date <= '2024-12-31'
           AND o.status = 'COMPLETED')
   AND u.is_active = TRUE
 ORDER BY u.username ASC;

TIP

• 여는 괄호 (는 서브쿼리를 사용하는 키워드(예: IN, =, EXISTS)와 같은 줄의 다음 줄로 내려 한 단계 들여씁니다. (위 예시는 다음 줄로 내린 형태)
• 이 들여쓰기를 기준으로 서브쿼리 내부의 River 스타일을 적용합니다.
• 서브쿼리 내부의 SELECT, FROM, WHERE 등의 키워드는 이 새로운 들여쓰기 수준에서 왼쪽 정렬됩니다.
• 닫는 괄호 )는 서브쿼리 내용이 끝난 후 줄에 삽입 합니다.
• 서브쿼리가 끝난 후 이어지는 외부 쿼리의 절(예: AND, OR, ORDER BY 등)은 기존 외부 쿼리의 River 흐름과 들여쓰기 수준으로 복귀합니다.

---

🧩 <include> 구문의 리버 적용 방식

✅ 예시

<select id="selectActiveUsers" resultType="User">
  <!--@formatter:off -->
  SELECT u.user_id
       , u.username
       , u.email
    FROM users AS u
   WHERE u.is_active = TRUE
    <include refId="A">
        <if test="B == B">
            <if test="C == C">
     AND B = B
            </if>
        </if>
    </include>
   ORDER BY u.username ASC
  <!--@formatter:on -->
</select>

WARNING

• <include> 나 <if> 와 같은 태그들은 xml indent convention 을 따릅니다 (4 blank spaces)
• 태그의 indent 와 상관없이 내부 쿼리문은 기존 river 에 맞게 정렬합니다.

💡 UserFilter.xml 내부 예시

<sql id="UserFilter">
  AND u.created_at >= #{startDate}
  AND u.created_at <= #{endDate}
</sql>

별도 정의된 <sql> 블록도 리버 스타일로 작성하여 일관성과 가독성을 유지합니다.