라이믹스/라우터

1. 개요#

라이믹스 2.0 버전에 추가된 기능으로, URL을 짧고 간결하게 만들어주는 역할을 한다. 예를 들어, 일반적인 URL 구조가 https://example.com/index.php?mid=board&document_srl=123라면, 라우터 기능을 통해 https://example.com/board/123와 같이 단순화할 수 있다. 이는 사용자가 URL을 쉽게 기억하고 입력할 수 있게 해준다.

2. 장점#

2.1. 간결한 URL#

복잡한 쿼리 스트링을 단순한 경로로 변환하여 가독성이 높다. 예를 들어 글 작성 페이지는 https://example.com/notice/write 형식으로 구성되어 있어, 기존 방식인 https://example.com/index.php?mid=notice&act=dispBoardWrite에 비해 어떤 mid, act인지 한눈에 이해하기 쉽다.

2.2. URL 공유와 가독성#

페이지의 역할이 드러나는 주소는 사용자가 읽고 공유하기 편하다. 다만 짧은주소를 사용한다는 사실만으로 검색 순위 향상이 보장되지는 않는다. 기존 주소와의 중복·리다이렉트·대표 URL도 함께 관리해야 한다.

2.3. 모듈화된 관리#

각 모듈이 자신만의 URL 패턴을 정의할 수 있어, 다양한 기능을 독립적으로 관리할 수 있다.

3. 사용법#

3.1. 사이트 적용#

사이트 내에 적용하기 위해서는 관리자 페이지(/admin)에 들어간 후, 설정 → 시스템 설정 → 고급 설정에서, 짧은 주소 사용 기능을 모든 주소 형태를 사용으로 변경한다.

짧은주소 수준은 0(사용 안 함), 1(XE와 호환되는 형태), 2(모든 형태)로 구분된다. 서버 rewrite 설정을 먼저 적용한 뒤 수준 2를 켜고 서드파티 자료를 확인한다. 문제가 생기면 기존 주소와 비교하여 rewrite와 모듈 라우팅 중 어느 단계의 문제인지 구분한다.

3.2. nginx 적용#

Apache는 배포된 .htaccess와 mod_rewrite, 해당 디렉터리의 설정 허용 여부를 확인한다. nginx는 별도 rewrite 규칙을 서버 설정에 포함해야 한다. 아래는 공식 규칙을 내려받는 예이며, 다운로드만으로 설정이 적용되는 것은 아니다.

curl https://raw.githubusercontent.com/rhymix/rhymix/master/common/manual/server_config/rhymix-nginx.conf > /etc/nginx/snippets/rhymix.conf

실제 server 블록의 include, PHP-FPM 경로, 설정 문법 검사와 적용은 라이믹스/매뉴얼/nginx 설정 방법을 따른다.

4. 개발자 가이드#

4.1. 모듈에서 라우터 사용#

라우터 기능을 사용하기 위해서는 module.xml 파일에서 route 속성을 정의해야 한다. 예를 들어, 게시판 모듈에서 특정 글의 삭제 확인 화면을 표시하는 URL을 정의하려면 다음과 같이 설정할 수 있다.

<action name="dispBoardDelete" type="view" route="$document_srl/delete" />

이렇게 하면 /board/123/delete가 dispBoardDelete 뷰 액션에 연결되고, Context::get('document_srl')로 123을 읽을 수 있다. 뷰에 접속하는 것과 실제 삭제 처리는 구분하며, 삭제 액션은 서버의 권한·CSRF 검사를 수행해야 한다. 또한, <route> 태그를 사용하면 하나의 액션에 여러 개의 짧은주소를 정의할 수 있다.

<action name="dispBoardWrite" type="view">
    <route route="write" />
    <route route="$document_srl/edit" />
</action>

위 설정을 적용하면 /notice/write와 /notice/123/edit와 같은 URL을 사용할 수 있다.

4.2. 우선순위 설정#

여러 개의 짧은주소가 동일한 변수들을 사용하여 충돌할 경우, priority 속성을 사용하여 우선순위를 지정할 수 있다.

<action name="dispBoardExample" type="view">
    <route route="downtown/$baby" priority="20" />
    <route route="hasta/la-vista/$baby" priority="10" />
</action>

같은 변수 조합으로 생성할 URL을 고르기 어려울 때 높은 priority의 형태가 선택된다. 이를 모든 요청의 일반적인 실행 순서와 혼동하지 않는다.

4.3. URL 생성과 남는 변수#

주소 문자열을 직접 조합하기보다 getUrl()로 액션과 인자를 전달하면 정의된 형태에 맞춰 생성한다. 같은 액션의 여러 route 중 주어진 변수와 맞는 형태를 선택하고, route에 들어가지 않는 변수는 쿼리스트링으로 남는다.

$url = getUrl([
    'mid' => 'board',
    'act' => 'dispBoardDelete',
    'document_srl' => 123,
]);

getUrl()의 반환값은 HTML용으로 이스케이프된다. 자세한 내용은 라이믹스/매뉴얼/전역 함수를 참고한다.

4.4. 변수 타입#

<action name="dispBoardMyAction" type="view" route="$name:alpha/$number:int" />

타입	허용 값
int / float	0 이상 정수 / 소수
alpha / alnum	영문자 / 영문자와 숫자
hex / word	16진수 문자 / 영문자·숫자·언더바
any	슬래시를 제외한 문자
delete	URL 생성 시 해당 변수를 경로와 쿼리스트링에서 제외

명시하지 않은 _srl 변수의 기본 타입은 int, 그 밖의 변수는 any이다. 복잡한 임의 정규식은 URL 역생성을 방해할 수 있어 지원하지 않는다. 타입 일치는 권한 검사와 별개이다.

4.5. 404 에러 처리#

라우트가 정의되지 않은 URL 요청이 들어오면, 모듈에서 404 에러 핸들러를 지정하여 사용자 친화적인 에러 페이지를 제공할 수 있다.

<action name="dispBoardNotFound" type="view" error-handlers="404" />

mid는 유효하지만 그 아래 경로가 일치하지 않을 때 지정한 dispBoardNotFound 메서드를 호출한다. 어느 모듈인지 찾을 수 없거나 핸들러가 없다면 코어의 404 화면을 표시한다.

4.6. 전역 짧은주소 사용#

mid 없이도 작동하는 기능(예: 통합검색)의 경우, global-route="true" 속성을 추가하여 전역 라우트를 설정할 수 있다.

<action name="IS" type="view" global-route="true">
    <route route="search" />
</action>

이를 통해 https://example.com/search와 같은 URL이 사용 가능하다. 다만, 전역 라우트는 다른 모듈과 충돌할 위험이 있으므로 신중하게 사용해야 한다.

5. 적용 후 점검#

모듈 선언을 바꾼 뒤 관리자 화면에서 필요한 모듈 업데이트와 캐시 재생성을 수행하고, URL 생성·직접 접속·없는 경로의 404를 확인한다. 전역 route는 다른 mid와 충돌할 수 있으므로 필요한 범위로 제한한다.

6. 같이 보기#

• 라이믹스/매뉴얼
• 라이믹스/매뉴얼/확장 기능 제작
• 라이믹스/매뉴얼/전역 함수
• 라이믹스/매뉴얼/nginx 설정 방법

7. 출처#

모듈에 라우터 사용하기 - 공식 매뉴얼을 바탕으로 작성하였다. 공식 매뉴얼은 CC BY-SA 4.0으로 배포된다.