eapim-admin/WebContent/guide/error-handling-setting-guide.md

# EAPIM 오류 변환 조건 등록 가이드

## 1. 메시지 키 등록 방법

### 1.1 메뉴 접근 경로

- 경로: 환경정보 > 어댑터 관리 > 메시지 키 관리

### 1.2 등록 화면 입력 항목

| 항목         | 설명                                                  | 입력 예시                                                                        |
| ------------ | ----------------------------------------------------- |------------------------------------------------------------------------------|
| 어댑터명     | 대상 어댑터 선택                                      | L_TST_OU_RST_SyCj REST Outbound Adapter For Test                             |
| 메시지유형   | JSON/XML 메시지 타입 선택                             | [JSN] JSON 또는 [XML] XML                                                      |
| 추출기능구분 | 고정값 지정                                           | O (고정)                                                                       |
| 업무필드명   | 추출할 필드명 지정<br>(아래 '1. 필드 추출 패턴' 참고) | - 일반: status<br>- JSON Path: $.response.status<br>- XPath: //response/status |
| 정상값       | 비교할 값 지정<br>(아래 '2. 비교 패턴' 참고)          | - 일반: 0000<br>- 예약어: @eq:0000<br>- 다중값: @contains:0000,2000                  |

### 1.2 등록 화면 예시

![메시지 키 등록 화면](assets/message-key-registration.png)

등록 화면 구성:
1. 어댑터명: `L_TST_OU_RST_SyC] REST Outbound Adapter For Test` 선택
2. 메시지유형: `[JSN] JSON` 선택
3. 추출기능구분: `[O] 응답메시지구분값 추출` 선택
4. 업무필드 목록:

   | 구분 | 업무필드명  | 필드시작위치 | 필드길이 | 정상값 |
   | ---- | ----------- | ------------ | -------- | ------ |
   | 1    | messageCode | 0            | 0        | 900    |

> **참고**: 위 예시는 'messageCode' 필드의 값이 900일 때 정상 응답으로 처리하는 설정입니다.

## 2. 필드 추출 패턴

필드명 정의 시 사용할 수 있는 패턴과 동작 방식을 설명합니다.

### 2.1 JSON 필드 추출

| 패턴        | 설명           | 예시                | 검색 방식                                     |
| ----------- | -------------- | ------------------- | --------------------------------------------- |
| 일반 필드명 | 단순 필드 접근 | `status`            | 전체 깊이 재귀 검색하여 첫번째 발견된 값 반환 |
| `$.`        | JSONPath 처리  | `$.response.status` | 명시적 경로로 검색                            |

**일반 필드명 검색 특징**:

- 재귀적 깊이 우선 검색
- 첫 번째 발견된 값 반환
- JSONObject와 JSONArray 모두 검색
- 대소문자 구분

예시) 필드명을 "status"로 검색하고 필드값을 "0000"으로 설정했을 때:

```json
{
   "status": "0000",             // 이 값이 먼저 발견되어 반환
   "data": {
      "status": "1111"           // 무시됨
   },
   "items": [
      {
         "status": "2222"        // 무시됨
      }
   ]
}
```

**JSONPath 패턴 예시**:

```json
$.orders[0].status           // 배열 첫 요소 접근
$.items[?(@.type=='book')]   // 조건부 필터링
$.prices[?(@>100)]           // 수치 기반 필터링
$..status                    // 모든 status 필드 검색
```

### 2.2 XML 필드 추출

| 패턴        | 설명           | 예시             | 검색 방식                 |
| ----------- | -------------- | ---------------- | ------------------------- |
| 일반 태그명 | 단순 태그 검색 | `status`         | 첫 번째 일치 태그 값 추출 |
| `//`        | XPath 처리     | `//order/status` | 전체 경로 기반 검색       |

**일반 태그명 검색 특징**:

- 단순 문자열 매칭으로 검색
- 첫 번째 발견된 태그만 처리
- 대소문자 구분
- 태그 속성 처리 불가
- 중첩 태그 내부 검색 불가

예시) 필드명을 "status"로 검색하고 필드값을 "0000"으로 설정했을 때:

```xml
<response>
   <status>0000</status>          <!-- 이 값이 반환됨 -->
   <data>
      <status>1111</status>       <!-- 무시됨 -->
   </data>
</response>
```

**XPath 패턴 예시**:

```xml
//order[@id='123']/status     <!-- 속성으로 필터링 -->
//items/item[1]/name          <!-- 인덱스로 접근 -->
//order[price>100]/status     <!-- 조건부 필터링 -->
//items//name                 <!-- 모든 하위 요소 검색 -->
```

## 3. 비교 패턴

### 3.1 일반 비교 (예약어 '@' 미사용)

- 예약어 없이 값을 직접 입력하는 경우 equals 비교를 수행

| 패턴          | 설명 | 예시   | 비교 결과                 |
| ------------- | ---- | ------ | ------------------------- |
| (예약어 없음) | 일치 | `0000` | 값이 "0000"과 정확히 일치 |

### 3.2 예약어 비교 패턴

모든 예약어는 `@` 접두어로 시작합니다.

#### 3.2.1 기본 비교

| 패턴     | 설명          | 예시       | 비교 결과                   |
| -------- | ------------- | ---------- | --------------------------- |
| `@eq:`   | 일치          | `@eq:0000` | 값이 "0000"과 정확히 일치   |
| `@ne:`   | 불일치        | `@ne:E001` | 값이 "E001"이 아님          |
| `@null`  | null 체크     | `@null`    | 값이 null 또는 빈 문자열    |
| `@!null` | not null 체크 | `@!null`   | 값이 존재하고 비어있지 않음 |

#### 3.2.2 문자열 패턴

| 패턴          | 설명   | 예시                  | 비교 결과                |
| ------------- | ------ | --------------------- | ------------------------ |
| `@contains:`  | 포함   | `@contains:0000,2000` | 나열된 값 중 하나와 일치 |
| `@!contains:` | 미포함 | `@!contains:ERROR`    | "ERROR" 문자열 미포함    |
| `@starts:`    | 시작값 | `@starts:P`           | "P"로 시작               |
| `@ends:`      | 종료값 | `@ends:OK`            | "OK"로 종료              |

#### 3.2.3 숫자 비교

| 패턴   | 설명 | 예시      | 비교 결과     |
| ------ | ---- | --------- | ------------- |
| `@gt:` | 초과 | `@gt:100` | 값이 100 초과 |
| `@lt:` | 미만 | `@lt:100` | 값이 100 미만 |
| `@ge:` | 이상 | `@ge:100` | 값이 100 이상 |
| `@le:` | 이하 | `@le:100` | 값이 100 이하 |

## 4. 통합 사용 예시

### 4.1 JSON 메시지 처리

```java
// 일반 필드명으로 상태 검색 - equals 비교
messageKeyVO.setBwkColNm("status");
messageKeyVO.setBwkColDef("SUCCESS");     // 단순 일치 비교

// 일반 필드명으로 상태 검색 - 예약어 비교
messageKeyVO.setBwkColNm("status");
messageKeyVO.setBwkColDef("@contains:SUCCESS,OK");

// JSONPath로 명시적 경로 검색
messageKeyVO.setBwkColNm("$.response.status");
messageKeyVO.setBwkColDef("@lt:500");
```

### 4.2 XML 메시지 처리

```java
// 일반 태그명으로 상태 코드 추출 - equals 비교
messageKeyVO.setBwkColNm("status");
messageKeyVO.setBwkColDef("0000");       // 단순 일치 비교

// 일반 태그명으로 상태 코드 추출 - 예약어 비교
messageKeyVO.setBwkColNm("status");
messageKeyVO.setBwkColDef("@eq:0000");   // 예약어 사용 일치 비교

// XPath로 특정 조건의 상태 코드 추출
messageKeyVO.setBwkColNm("//response/data[@type='main']/status");
messageKeyVO.setBwkColDef("@contains:0000,2000");

// 에러 메시지 null 체크
messageKeyVO.setBwkColNm("errorMessage");
messageKeyVO.setBwkColDef("@null");
```

## 5. 주의사항

### 5.1 필드 추출 시

1. JSON 검색
   - 일반 필드명은 전체 깊이 검색으로 성능 고려 필요
   - 명확한 경로를 알 경우 JSONPath 사용 권장
   - 동일 키가 여러 곳에 있는 경우 JSONPath로 명시적 지정

2. XML 검색
   - 일반 태그명 사용 시 첫 번째 일치 태그만 처리
   - 태그 속성이 있는 경우 XPath 사용 권장
   - 중첩 구조에서는 XPath 사용 권장

### 5.2 비교 패턴 사용 시

- 예약어가 없는 경우 단순 equals 비교 수행
- 모든 예약어는 `@`로 시작
- 숫자 비교 시 숫자 형식이 아닌 경우 false 반환
- `@contains:`는 콤마로 구분된 여러 값 비교 가능

## 6. 예외 처리

| 상황                       | 처리 방식      |
| -------------------------- | -------------- |
| 잘못된 XML 태그            | 빈 문자열 반환 |
| 잘못된 XPath               | 빈 문자열 반환 |
| 잘못된 JSONPath            | 빈 문자열 반환 |
| 존재하지 않는 필드         | 빈 문자열 반환 |
| null 값                    | 빈 문자열 반환 |
| 숫자가 아닌 값의 숫자 비교 | false 반환     |
| 인식할 수 없는 예약어      | false 반환     |