패키지 레벨 반복 함수

Processor 인스턴스를 생성하지 않고 직접 호출할 수 있는 반복 함수입니다. Processor 반복 메서드와 일대일로 대응됩니다 (이중 계층 설계).

Foreach

시그니처: func Foreach(jsonStr string, fn func(key any, item *IterableValue), cfg ...Config)

JSON 배열 또는 객체를 순회합니다.

json.Foreach(data, func(key any, item *json.IterableValue) {
    fmt.Printf("Key: %v, Value: %v\n", key, item.GetData())
})

배열 순회 시: key 는 인덱스 (int) 객체 순회 시: key 는 키 이름 (string)

ForeachWithPath

시그니처: func ForeachWithPath(jsonStr, path string, fn func(key any, item *IterableValue), cfg ...Config) error

경로를 따라 순회하며, 오류를 반환합니다.

err := json.ForeachWithPath(data, "items", func(key any, item *json.IterableValue) {
    fmt.Printf("[%v] %v\n", key, item.GetData())
})

적용 사례:

• 중첩 배열 순회
• 지정된 경로의 객체 순회

ForeachNested

시그니처: func ForeachNested(jsonStr string, fn func(key any, item *IterableValue), cfg ...Config)

모든 중첩 수준을 재귀적으로 순회합니다.

json.ForeachNested(data, func(key any, item *json.IterableValue) {
    fmt.Printf("키: %v, 값: %v\n", key, item.GetData())
})

예제 데이터:

{
  "user": {
    "name": "test",
    "profile": {
      "age": 25,
      "tags": ["a", "b"]
    }
  }
}

출력:

키: user, 값: map[string]any{...}
키: name, 값: test
키: profile, 값: map[string]any{...}
키: age, 값: 25
키: tags, 값: []any{...}
...

ForeachReturn

시그니처: func ForeachReturn(jsonStr string, fn func(key any, item *IterableValue), cfg ...Config) (string, error)

JSON 데이터를 순회하며 콜백으로 각 요소에 접근하고, 다시 직렬화한 JSON 문자열을 반환합니다. 콜백은 GetData()를 통해 map/slice를 수정할 수 있으며, 수정 사항은 반환값에 반영됩니다.

result, err := json.ForeachReturn(data, func(key any, item *json.IterableValue) {
    // item.GetData() 로 요소에 접근/수정 가능
})

순회 후 체인 작업을 이어가야 하는 시나리오에 적합합니다.

ForeachWithError

시그니처: func ForeachWithError(jsonStr, path string, fn func(key any, item *IterableValue) error, cfg ...Config) error

경로를 따라 순회하며, 콜백이 오류를 반환할 수 있습니다.

err := json.ForeachWithError(data, "items", func(key any, item *json.IterableValue) error {
    if item.GetInt("id") == 0 {
        return fmt.Errorf("invalid item at index %v", key)
    }
    return nil // 반복 계속
})

ForeachNestedWithError

시그니처: func ForeachNestedWithError(jsonStr string, fn func(key any, item *IterableValue) error, cfg ...Config) error

모든 중첩 수준을 재귀적으로 순회하며, 콜백이 오류를 반환할 수 있습니다.

err := json.ForeachNestedWithError(data, func(key any, item *json.IterableValue) error {
    fmt.Printf("키: %v, 값: %v\n", key, item.GetData())
    return nil
})

ForeachWithPathAndIterator

시그니처: func ForeachWithPathAndIterator(jsonStr, path string, fn func(key any, item *IterableValue, currentPath string) IteratorControl, cfg ...Config) error

경로를 따라 순회하며 현재 경로 정보를 제공합니다. IteratorControl로 반복 흐름을 제어합니다.

err := json.ForeachWithPathAndIterator(data, "items", func(key any, item *json.IterableValue, currentPath string) json.IteratorControl {
    fmt.Printf("경로: %s, 키: %v\n", currentPath, key)
    if item.GetInt("id") == targetID {
        return json.IteratorBreak // 반복 중단
    }
    return json.IteratorNormal // 반복 계속
})

ForeachWithPathAndControl

시그니처: func ForeachWithPathAndControl(jsonStr, path string, fn func(key any, value any) IteratorControl, cfg ...Config) error

경로를 따라 원시 값을 순회하며, IteratorControl로 흐름을 제어합니다.

err := json.ForeachWithPathAndControl(data, "items", func(key any, value any) json.IteratorControl {
    fmt.Printf("키: %v, 값: %v\n", key, value)
    return json.IteratorNormal
})

IterableValue

반복 콜백의 IterableValue는 편리한 값 접근 기능을 제공합니다. 전체 메서드 정의는 반복기 타입을 참조하세요.

메서드	설명
GetData() any	현재 값 가져오기
Get(path string) any	경로로 값 가져오기
GetString(key string) string	문자열 값 가져오기
GetInt(key string) int	정수 값 가져오기
GetFloat64(key string) float64	부동소수점 값 가져오기
GetBool(key string) bool	불리언 값 가져오기
GetArray(key string) []any	배열 값 가져오기
GetObject(key string) map[string]any	객체 값 가져오기
Exists(key string) bool	필드 존재 여부 확인
IsNull(key string) bool / IsNullData() bool	null 여부 확인
IsEmpty(key string) bool / IsEmptyData() bool	빈 값 여부 확인
Break() error	반복 중단 오류 신호 반환
Release()	객체 풀로 리소스 반환

메서드 비교

메서드	경로 매개변수	재귀	반환값	오류 콜백
Foreach	없음	아니오	없음	아니오
ForeachWithPath	있음	아니오	error	아니오
ForeachNested	없음	예	없음	아니오
ForeachReturn	없음	아니오	(string, error)	아니오
ForeachWithError	있음	아니오	error	예
ForeachNestedWithError	없음	예	error	예
ForeachWithPathAndIterator	있음	아니오	error	IteratorControl
ForeachWithPathAndControl	있음	아니오	error	IteratorControl

---

파일 반복 함수

패키지 레벨에서 파일로부터 직접 반복하는 함수를 제공합니다. 대용량 JSON 파일 처리에 적합하며, Processor 파일 반복 메서드와 대응됩니다.

ForeachFile

시그니처: func ForeachFile(filePath string, fn func(key any, item *IterableValue) error, cfg ...Config) error

파일에서 JSON 을 로드하여 반복합니다.

매개변수

이름	타입	설명
filePath	string	JSON 파일 경로
fn	func(key any, item *IterableValue) error	반복 콜백

err := json.ForeachFile("data.json", func(key any, item *json.IterableValue) error {
    fmt.Printf("[%v] %v\n", key, item.GetData())
    return nil // 반복 계속
})

---

ForeachFileWithPath

시그니처: func ForeachFileWithPath(filePath, path string, fn func(key any, item *IterableValue) error, cfg ...Config) error

파일에서 JSON 을 로드하고 경로를 따라 반복합니다.

// users 배열만 반복
err := json.ForeachFileWithPath("data.json", ".users", func(key any, item *json.IterableValue) error {
    name := item.GetString("name")
    fmt.Printf("사용자: %s\n", name)
    return nil
})

---

ForeachFileChunked

시그니처: func ForeachFileChunked(filePath string, chunkSize int, fn func(chunk []*IterableValue) error, cfg ...Config) error

파일 내 JSON 배열을 청크 단위로 반복합니다. 대용량 데이터셋의 배치 처리에 적합합니다.

매개변수

이름	타입	설명
filePath	string	JSON 파일 경로
chunkSize	int	배치당 처리 수량 (≤0 이면 기본값 100)
fn	func(chunk []*IterableValue) error	배치 처리 콜백

// 한 번에 100 개 레코드씩 처리
err := json.ForeachFileChunked("large_data.json", 100, func(chunk []*json.IterableValue) error {
    // 데이터베이스 일괄 삽입
    records := make([]Record, len(chunk))
    for i, item := range chunk {
        records[i] = Record{
            ID:   item.GetInt("id"),
            Name: item.GetString("name"),
        }
    }
    return db.BatchInsert(records)
})

사용 사례

• 데이터베이스 일괄 삽입
• 분할 API 호출
• 메모리 제약이 있는 대용량 파일 처리

---

ForeachFileNested

시그니처: func ForeachFileNested(filePath string, fn func(key any, item *IterableValue) error, cfg ...Config) error

파일에서 JSON 을 로드하고 모든 중첩 구조를 재귀적으로 반복합니다.

err := json.ForeachFileNested("config.json", func(key any, item *json.IterableValue) error {
    // 모든 수준의 모든 키 - 값 쌍 순회
    fmt.Printf("경로: %v, 타입: %T\n", key, item.GetData())
    return nil
})

예제 데이터:

{
  "database": {
    "host": "localhost",
    "port": 5432,
    "pool": {
      "min": 5,
      "max": 20
    }
  }
}

출력:

경로: database, 타입: map[string]any
경로: host, 타입: string
경로: port, 타입: float64
경로: pool, 타입: map[string]any
경로: min, 타입: float64
경로: max, 타입: float64

---

파일 반복 메서드 비교

메서드	경로 매개변수	재귀	청크	적합한 사례
ForeachFile	없음	아니오	아니오	단순 파일 순회
ForeachFileWithPath	있음	아니오	아니오	특정 위치 순회
ForeachFileChunked	없음	아니오	예	배치 처리, 메모리 제약
ForeachFileNested	없음	예	아니오	모든 노드 깊이 순회

---

반복 제어

IteratorControl 상수

ForeachWithPathAndControl와 ForeachWithPathAndIterator는 IteratorControl을 반환하여 반복 흐름을 제어합니다 (상수 정의는 반복기 타입 참조):

상수	설명
IteratorNormal	정상적으로 반복 계속
IteratorContinue	현재 항목 건너뛰고 반복 계속
IteratorBreak	반복 중단

반복 중단

오류 콜백에서 item.Break()를 반환하면 반복을 중단할 수 있습니다:

err := json.ForeachFile("data.json", func(key any, item *json.IterableValue) error {
    if item.GetInt("id") == targetID {
        // 대상을 찾음, 반복 중단
        return item.Break()
    }
    return nil // 반복 계속
})

오류 처리

다른 오류를 반환하면 반복이 중단되고 해당 오류가 반환됩니다:

err := json.ForeachFile("data.json", func(key any, item *json.IterableValue) error {
    if item.GetString("status") == "error" {
        return fmt.Errorf("오류 레코드 발견: %v", key)
    }
    return nil
})
if err != nil {
    log.Printf("반복 중단: %v", err)
}

---

관련 문서

• Processor 반복 메서드 - 대응되는 프로세서 메서드
• 반복기 타입 - Iterator/IterableValue/Stream/Batch/Parallel 타입 정의
• 경로 조회 - Get 계열 메서드
• 배치 작업 - ProcessBatch 배치 처리
• 파일 작업 - LoadFromFile/SaveToFile
• 대용량 파일 처리 가이드 - 스트리밍 처리 사례 실무