Update

Author: topframe

_pages/en/docs/guides/aspectran-translet.md

@@ -29,22 +29,35 @@ A single Translet defines the processing flow for a specific request. This can i
 -   **Action Execution**: Defines which business logic to perform.
 -   **Content Generation**: Combines processing results to generate content for the response.
 -   **Transformation**: Transforms the generated content into a final response format like JSON, XML, or text.
--   **Response and Dispatch**: Responds to the user with the final result or forwards the processing to another Translet.
+-   **Response Control**: Allows you to directly respond with data like JSON or XML, dispatch to a view template for UI rendering, or forward/redirect the processing to another Translet or URL.
 
 By combining these rules, you can flexibly design everything from very simple tasks to complex workflows.
 
 ## 2. How is a Translet Found and Executed?
 
 When the application starts, Aspectran parses all defined Translet rules and registers them in a central repository called the **`TransletRuleRegistry`**.
 
-When a user request comes in, the `Activity` finds the most suitable Translet rule (blueprint) from this registry.
+When a user request comes in, the `Activity` finds the most suitable Translet rule (blueprint) from this registry. Aspectran searches for rules based on a clear priority system, ensuring that the most specific rule is always chosen first.
 
 1.  **Request Name**: It looks for an exact match, like `/user/info`.
 2.  **Request Method**: In a web environment, this corresponds to HTTP methods like `GET`, `POST`, etc. Even with the same request name, a different Translet can be executed based on this request method.
 3.  **Wildcard and Path Variable Patterns**: It supports patterns like `/users/*` or `/users/${userId}`, allowing for very efficient implementation of RESTful APIs.
 
 The `Activity` performs the actual request processing task according to the found Translet rule. In other words, **the Translet is the 'blueprint', and the Activity is the 'construction worker'** that works by looking at that blueprint.
 
+### Search Priority: The Most Specific Rule Wins!
+
+When finding a Translet, the following priorities are applied:
+
+1.  **Exact Match First**: Rules with a name that exactly matches the request, without any wildcards (`*`) or path variables (`${...}`), are always chosen first.
+2.  **More Specific Patterns Take Precedence**: If multiple wildcard patterns match a request, the rule with the more specific pattern wins.
+    -   **Example**: For a `GET /users/info` request, if both a `/users/*` rule and a `/users/info` rule exist, the more specific `/users/info` rule will be selected. Similarly, a `/users/${userId}/profile` pattern is more specific than `/users/${userId}/*` and would be chosen first.
+3.  **Fallback for Non-GET Requests**: If no exact match is found for a `POST`, `PUT`, etc., request, Aspectran will look for a rule that has no method specified (implicitly a `GET` rule) as a fallback.
+    -   **Example**: If a `POST /users` request arrives, but there is no `/users` rule explicitly defined with `method="post"`, and only a `<translet name="/users">...</translet>` rule (with no method) exists, that rule will be selected to handle the request.
+4.  **Later Definitions Override Earlier Ones**: If multiple Translet rules are defined with the same request name and method, the **last one defined (or registered)** will overwrite the previous ones. This can be useful for overriding specific rules when your Aspectran configuration is split across multiple files or when using the include feature to import settings from another file.
+
+This priority system allows developers to define general-purpose rules alongside specific ones, leading to flexible and intuitive code management.
+
 ## 3. Dynamic Translet Generation (Scanning)
 
 One of Aspectran's most powerful features is **dynamic Translet generation**. For example, if you need to serve hundreds of JSP files as different Translets, instead of repeatedly defining hundreds of `<translet>` rules, you can define just one rule as follows:

_pages/ko/docs/guides/aspectran-translet.md

@@ -29,22 +29,35 @@ Translet은 XML 또는 APON(Aspectran Object Notation) 형식의 **선언적인
 -   **액션(Action) 실행**: 어떤 비즈니스 로직을 수행할지 정의합니다.
 -   **콘텐츠(Content) 생성**: 처리 결과를 조합하여 응답할 콘텐츠를 생성합니다.
 -   **변환(Transform)**: 생성된 콘텐츠를 JSON, XML, 텍스트 등 최종적인 응답 형태로 변환합니다.
--   **응답(Response) 및 전달(Dispatch)**: 최종 결과를 사용자에게 응답하거나, 다른 Translet으로 처리를 전달합니다.
+-   **응답(Response) 제어**: 처리 결과를 JSON, XML 같은 데이터로 직접 응답하거나, 뷰 템플릿으로 디스패치(Dispatch)하여 UI를 렌더링하거나, 다른 Translet으로 포워드(Forward) 또는 리다이렉트(Redirect)할 수 있습니다.
 
 이러한 규칙들을 조합하여 매우 단순한 작업부터 복잡한 워크플로우까지 유연하게 설계할 수 있습니다.
 
 ## 2. Translet은 어떻게 찾아지고 실행되는가?
 
 애플리케이션이 시작될 때, Aspectran은 정의된 모든 Translet 규칙을 파싱하여 **`TransletRuleRegistry`**라는 중앙 저장소에 등록합니다.
 
-사용자의 요청이 들어오면, `Activity`는 이 레지스트리에서 가장 적합한 Translet 규칙(설계도)을 찾아냅니다.
+사용자의 요청이 들어오면, `Activity`는 이 레지스트리에서 가장 적합한 Translet 규칙(설계도)을 찾아냅니다. Aspectran은 명확한 우선순위에 따라 규칙을 검색하여 항상 가장 구체적인 규칙이 먼저 선택되도록 보장합니다.
 
 1.  **요청 이름 (Request Name)**: `/user/info`와 같이 정확히 일치하는 이름을 찾습니다.
 2.  **요청 메소드 (Request Method)**: 웹 환경에서는 `GET`, `POST` 등의 HTTP 메소드가 여기에 해당하며, 같은 요청 이름이라도 이 요청 메소드에 따라 다른 Translet을 실행할 수 있습니다.
 3.  **와일드카드 및 경로 변수 패턴**: `/users/*`나 `/users/${userId}`와 같은 패턴을 지원하여 RESTful API를 매우 효율적으로 구현할 수 있습니다.
 
 `Activity`는 찾아낸 Translet 규칙에 따라 실제 요청 처리 작업을 수행합니다. 즉, **Translet은 '설계도'이고 Activity는 그 설계도를 보고 일하는 '건설 인부'**와 같습니다.
 
+### 검색 우선순위: 가장 구체적인 규칙이 먼저!
+
+Translet을 찾을 때는 다음과 같은 우선순위가 적용됩니다.
+
+1.  **완전 일치 (Exact Match)가 최우선**: 와일드카드(`*`)나 경로 변수(`${...}`)가 없는, 이름이 완전히 일치하는 규칙이 가장 먼저 선택됩니다.
+2.  **더 구체적인 패턴이 우선**: 여러 와일드카드 패턴이 일치할 경우, 더 구체적인 패턴을 가진 규칙이 우선권을 갖습니다.
+    -   **예시**: `GET /users/info` 요청이 들어왔을 때, `/users/*` 규칙과 `/users/info` 규칙이 모두 존재한다면, 더 구체적인 `/users/info` 규칙이 선택됩니다. 마찬가지로, `/users/${userId}/profile` 패턴은 `/users/${userId}/*` 패턴보다 더 구체적이므로 우선 선택됩니다.
+3.  **GET이 아닌 요청의 대체(Fallback) 규칙**: `POST`, `PUT` 등의 요청에 대해 정확히 일치하는 규칙이 없다면, Aspectran은 메소드가 지정되지 않은(암묵적 `GET`) 규칙을 차선책으로 찾습니다.
+    -   **예시**: `POST /users` 요청이 들어왔는데 `method="post"`로 명시된 `/users` 규칙이 없고, 메소드 지정 없이 정의된 `<translet name="/users">...</translet>` 규칙만 있다면, 이 규칙이 선택되어 처리됩니다.
+4.  **나중에 정의된 규칙이 우선 (규칙 덮어쓰기)**: 만약 동일한 요청 이름과 메소드를 가진 Translet 규칙이 여러 번 정의되면, **가장 나중에 정의(등록)된 규칙**이 이전에 정의된 규칙을 덮어쓰고 최종적으로 사용됩니다. 이는 Aspectran 설정 파일이 여러 개로 분리되어 있거나, include 기능으로 다른 파일의 설정을 가져올 때 특정 규칙을 오버라이드(override)하는 용도로 유용하게 사용될 수 있습니다.
+
+이러한 우선순위 덕분에 개발자는 일반적인 경우를 처리하는 규칙과 특정 경우를 처리하는 규칙을 함께 정의하여 코드를 유연하고 직관적으로 관리할 수 있습니다.
+
 ## 3. 동적 Translet 생성 (Scanning)
 
 Aspectran의 가장 강력한 기능 중 하나는 **동적 Translet 생성**입니다. 예를 들어, 수백 개의 JSP 파일을 각각 다른 Translet으로 서빙해야 할 때, 수백 개의 `<translet>` 규칙을 반복해서 정의하는 대신, 다음과 같이 단 하나의 규칙만 정의할 수 있습니다.
@@ -121,4 +134,4 @@ Translet의 진정한 역할은 이 둘 사이의 **'소통을 위한 인터페
 *   **데이터 저장소**: `Activity`가 처리한 결과(`ProcessResult`)를 보관하여 사용자 코드가 접근할 수 있도록 합니다.
 *   **제어 통로**: 사용자 코드가 `Translet` 인스턴스를 통해 응답 방식을 일부 제어할 수 있는 통로를 제공합니다.
 
-이처럼 Translet은 복잡한 내부 실행 로직(`Activity`)을 감추고 사용자에게는 명확하고 단순한 '설계도'와 '인터페이스'만을 보여줍니다. 이러한 역할 덕분에 개발자는 내부의 복잡한 동작을 몰라도 애플리케이션의 기능을 쉽고 유연하게 설계하고 확장해 나갈 수 있습니다.
+이처럼 Translet은 복잡한 내부 실행 로직(`Activity`)을 감추고 사용자에게는 명확하고 단순한 '설계도'와 '인터페이스'만을 보여줍니다. 이러한 역할 덕분에 개발자는 내부의 복잡한 동작을 몰라도 애플리케이션의 기능을 쉽고 유연하게 설계하고 확장해 나갈 수 있습니다.