llm-wiki/raw/official-docs/mapstruct-generated-annotation-official.md

---
title: "official-doc / MapStruct — @Generated Annotation, Processor Options, Java Module System (Stable Reference)"
source_type: official-doc
url: https://mapstruct.org/documentation/stable/reference/html/
archive_url:
related_branches: [feature-architecture-enforcement-rules]
related_projects: [ca-skeleton]
tags: [official-doc, ca-skeleton, architecture, mapstruct, code-generation]
created: 2026-05-28
status: raw
confidence: high
last_reviewed: 2026-05-28
---

# official-doc / MapStruct — @Generated Annotation, Processor Options, Java Module System

> Layer: `raw/official-docs/` — MapStruct 공식 레퍼런스 문서 원문 발췌.
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 별도 작성. 원본은 raw에 영구 보관.

## Parent / 활용 branch

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-architecture-enforcement-rules]] | D9: MapStruct generated mapper에 대한 ArchUnit exemption 근거 — MapStruct가 `@Generated` annotation을 붙인다는 공식 확인, 및 `java.annotation.processing.Generated`가 Java 9+ 모듈 시스템에서 활성화 가능하다는 공식 근거 |

## 출처 / Source

- 원본 URL: https://mapstruct.org/documentation/stable/reference/html/
- 아카이브 URL: (미등록 — 최초 캡처)
- 저자 / 조직: MapStruct Authors (mapstruct.org)
- 발행일: (stable reference — 버전별 갱신)
- 마지막 확인일: 2026-05-28

## 왜 저장했는지 / Why archived

`feature-architecture-enforcement-rules`의 D9가 `UNSUPPORTED_DECISION` 상태로, MapStruct generated code에 대한 ArchUnit exemption의 공식 근거가 없었다. MapStruct 공식 레퍼런스의 §2.4 Processor Options 표와 §2.5 Java Module System 절이 `@Generated` annotation 동작과 `java.annotation.processing.Generated` 활성화를 명시적으로 문서화하고 있으므로, D9의 exemption 패턴에 대한 공식 vendor-doc 근거로 보관한다.

## 핵심 인용 / Key quotes (verbatim)

> [§2.5, line 1276] "To allow usage of the `@Generated` annotation `java.annotation.processing.Generated` (part of the `java.compiler` module) can be enabled."

> [§2.4 Table 1, line 1078] "If set to `true`, the creation of a time stamp in the `@Generated` annotation in the generated mapper classes is suppressed."

> [§2.4 Table 1, line 1093] "If set to `true`, the creation of the `comment` attribute in the `@Generated` annotation in the generated mapper classes is suppressed. The comment contains information about the version of MapStruct and about the compiler used for the annotation processing."

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| MS-ANNOT-C1 | MapStruct generated mapper 클래스에는 `@Generated` annotation이 붙는다 | [§2.4 Table 1, line 1078] "the creation of a time stamp in the `@Generated` annotation in the generated mapper classes" | `official-vendor-doc` | MapStruct annotation processor를 사용하는 모든 Java 프로젝트 | `@Generated`가 ArchUnit 규칙에서 자동으로 exemption 처리됨을 의미하지 않음. ArchUnit 규칙 측에서 명시 처리 필요 |
| MS-ANNOT-C2 | Java 9 이상에서 `java.annotation.processing.Generated` (`java.compiler` 모듈 소속)을 활성화하면 `@Generated` annotation 사용이 가능하다 | [§2.5, line 1276] "To allow usage of the `@Generated` annotation `java.annotation.processing.Generated` (part of the `java.compiler` module) can be enabled." | `official-vendor-doc` | Java 9+ 모듈 시스템 사용 프로젝트 | `java.compiler` 모듈이 기본 활성화됨을 의미하지 않음. 빌드 설정에서 명시 추가 필요 여부는 빌드 도구와 환경에 따름 |
| MS-ANNOT-C3 | `mapstruct.suppressGeneratorTimestamp=true` 옵션으로 생성된 mapper의 `@Generated` annotation에서 타임스탬프를 제거할 수 있다 | [§2.4 Table 1, line 1078] "If set to `true`, the creation of a time stamp in the `@Generated` annotation in the generated mapper classes is suppressed." | `official-vendor-doc` | MapStruct processor option 설정이 가능한 모든 빌드 환경 (Maven/Gradle) | 기본값은 `false` (타임스탬프 포함). ca-tmpl이 현재 이 옵션을 설정하는지는 별도 확인 필요 |
| MS-ANNOT-C4 | `mapstruct.suppressGeneratorVersionInfoComment=true` 옵션으로 `@Generated` annotation의 `comment` attribute (MapStruct 버전 + 컴파일러 정보)를 제거할 수 있다 | [§2.4 Table 1, line 1093] "If set to `true`, the creation of the `comment` attribute in the `@Generated` annotation in the generated mapper classes is suppressed. The comment contains information about the version of MapStruct and about the compiler used for the annotation processing." | `official-vendor-doc` | MapStruct processor option 설정이 가능한 모든 빌드 환경 | 기본값은 `false` (version info 포함). D9 exemption 로직과 직접적 연관은 없으나 build reproducibility에 영향 |

### Strength 허용값 참고

사용한 Strength: `official-vendor-doc` — MapStruct 공식 vendor 문서.

## Usage Boundaries / 적용 경계

- 이 자료가 직접 증명하는 것:
  - `MS-ANNOT-C1`: MapStruct가 generated mapper에 `@Generated` annotation을 부착한다는 것 (타임스탬프 suppress 옵션 문서에서 직접 확인됨)
  - `MS-ANNOT-C2`: Java 9 이상에서 `java.annotation.processing.Generated` annotation 사용이 MapStruct에 의해 지원된다는 것
  - `MS-ANNOT-C3`: `mapstruct.suppressGeneratorTimestamp` processor option의 동작
  - `MS-ANNOT-C4`: `mapstruct.suppressGeneratorVersionInfoComment` processor option의 동작
- 이 자료가 증명하지 않는 것:
  - ArchUnit에서 `@Generated` annotation 보유 클래스를 자동 제외하는 방법 — ArchUnit 측 DSL/predicate 구현은 ArchUnit 공식 문서 참조 필요
  - ca-tmpl 프로젝트의 실제 generated source path가 어디인지 — 빌드 설정 확인 필요
  - `java.compiler` 모듈이 ca-tmpl 빌드에서 현재 활성화되어 있는지
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - ca-tmpl의 MapStruct annotation processor가 실제로 어떤 `@Generated` annotation 클래스를 사용하는지 (`javax.annotation.Generated` vs `java.annotation.processing.Generated`) — Java 버전에 따라 다름
  - ArchUnit의 `.that(have(simpleNameStartingWith("..."))` 또는 `.that(areAnnotatedWith(Generated.class))` predicate가 실제로 generated mapper를 식별하는지 ca-tmpl 테스트에서 검증 필요
  - 두 annotation 클래스 중 어느 것이 ArchUnit `haveSimpleName` / `areAnnotatedWith` 조건에 매칭되는지

## 메모 / Notes

- MapStruct가 `@Generated`를 붙인다는 사실은 §2.4 Table 1의 `suppressGeneratorTimestamp` 옵션 설명에서 간접적으로 확인된다 (타임스탬프를 suppress하는 옵션이 있다는 것은 기본값으로 타임스탬프가 포함된 `@Generated`가 생성됨을 전제).
- §2.5는 매우 짧은 절로, Java 모듈 시스템 지원에 대한 상세 설명 없이 `java.compiler` 모듈 활성화만 언급한다. 상세 module-info.java 설정은 별도 확인 필요.
- 추가로 봐야 할 동일 출처 페이지: MapStruct reference의 "Using MapStruct with Java 9" 또는 module-info.java 설정 예제 (stable 레퍼런스 내 다른 절 또는 migration guide).

## Related / 관련

- 같은 주제 ArchUnit 공식 문서: [[raw/official-docs/archunit-user-guide]]
- 같은 주제 ArchUnit governance: [[raw/official-docs/governance-archunit-official]]
- 이 자료를 인용한 branch-note: [[raw/branch-notes/feature-architecture-enforcement-rules]]