https://cheroliv.com/ JBake 부트스트랩 템플릿 en-gb Thu, 8 Oct 2026 11:38:17 +0000 Thu, 8 Oct 2026 11:38:17 +0000 https://cheroliv.com/blog/2026/0126_hyperframes_asciidoc_video_post.html Sun, 31 May 2026 00:00:00 +0000 blog/2026/0126_hyperframes_asciidoc_video_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_비디오_파이프라인의_구멍">비디오 파이프라인의 구멍</a></li> <li><a href="#_hyperframes_엔진">HyperFrames : 엔진</a></li> <li><a href="#_플러그인_아키텍처">플러그인 아키텍처</a> <ul class="sectlevel2"> <li><a href="#_네_단계_파이프라인">네 단계 파이프라인</a></li> <li><a href="#_asciidoc_dsl">AsciiDoc DSL</a></li> <li><a href="#_bridge_node_js">Bridge Node.js</a></li> </ul> </li> <li><a href="#_두_개의_비디오_플러그인_두_가지_용도">두 개의 비디오 플러그인, 두 가지 용도</a></li> <li><a href="#_로드맵의_6개_에픽">로드맵의 6개 에픽</a></li> <li><a href="#_왜_동작하나요">왜 동작하나요?</a></li> <li><a href="#_결론_잃어버린_고리">결론: 잃어버린 고리</a></li> <li><a href="#_참고문헌">참고문헌</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽는 시간 : 8 minutes</div> <p>두 주 전에, 내가 시작했다`capsule-gradle`덱을 변환하는 플러그인 reveal.js의 WebM 비디오 캡슐에 TTS가 적용된 것입니다. 오늘, 새로운 플러그인을 추가합니다 : `hyperframes-gradle`それが capsule-gradle가 하지 않는 무언가를 수행합니다 : AsciiDoc을 <strong>직접</strong> MP4 영상으로 변환하기, reveal.js를 거치지 않고.</p> </div> <div class="paragraph"> <p>이 플러그인이 존재하는 이유와 기존 시스템과의 연동 방식은 다음과 같습니다, 그리고 HeyGen의 HyperFrames 엔진이 콘텐츠 제작 파이프라인에 제공하는 것.</p> </div> </div> </div> <div class="sect1"> <h2 id="_비디오_파이프라인의_구멍">비디오 파이프라인의 구멍</h2> <div class="sectionbody"> <div class="paragraph"> <p>내 다큐멘터리 파이프라인은 두 가지 유형의 비디오를 생산합니다 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>복습 캡슐</strong> (capsule-gradle) — WebM으로 캡처된 reveal.js 덱과</p> </li> </ol> </div> <div class="paragraph"> <p>narration TTS. 모듈을 복습하기에 완벽합니다.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>애니메이션 슬라이드</strong> (slider-gradle) — 인터랙티브 reveal.js HTML 데크를 위한</p> </li> </ol> </div> <div class="paragraph"> <p>대면 강사</p> </div> <div class="paragraph"> <p>하지만 세 번째 형식이 없습니다 : <strong>독립형 비디오</strong></p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5565%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">사용 사례</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">현재 솔루션</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">부족</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">강사용 슬라이드</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">slider-gradle → reveal.js</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">수정 캡슐</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">capsule-gradle → WebM</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>티저 영상</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>A무것도</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">애니메이션된 기술 데모</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>아무것도</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>문서-비디오</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>없음</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>첫 번째 use case는 중요합니다 : 어떻게 자동으로 생성할 수 있나요 GSAP 애니메이션이 포함된, 프로젝트 또는 모듈을 소개하는 60초 비디오, TTS 내레이션, 배경 음악 — 모두 동일한 AsciiDoc 파일에서 슬라이드는?</p> </div> <div class="paragraph"> <p>Capsule-gradle은 응답할 수 없습니다: <strong>이미</strong> reveal.js 덱이 필요합니다. slider-gradle는 이 데크를 잘 생성하지만, 비디오 렌더링용으로 설계되지 않았습니다. 직접적인 파이프라인이 필요했습니다: AsciiDoc → 비디오</p> </div> </div> </div> <div class="sect1"> <h2 id="_hyperframes_엔진">HyperFrames : 엔진</h2> <div class="sectionbody"> <div class="paragraph"> <p>발견했다https://github.com/heygen-com/hyperframes[하이퍼프레임] il y a 며칠. HeyGen이 만든 Apache 2.0 라이선스의 오픈소스 프레임워크, AI 비디오의 유니콘. GitHub에서 별 22,700개. 피치는 문장 :</p> </div> <div class="paragraph"> <p><strong>HTML 작성. 비디오 렌더링. 에이전트를 위한 설계.</strong></p> </div> <div class="paragraph"> <p>원칙 : HTML을 작성합니다.`data-*`속성, 참조합니다 GSAP 애니메이션 (또는 CSS, Lottie, Three.js… 등)이며, 엔진이 이를 모두 MP4로 렌더링 Puppeteer (헤드리스 크롬) + FFmpeg를 통해. 결정론적 결과: 동일한 입력, 같은 프레임, 같은 비디오.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><div id="stage" data-composition-id="intro" data-start="0" data-width="1920" data-height="1080"> <video class="clip" data-start="0" data-duration="6" data-track-index="0" src="background.mp4" muted playsinline></video> <h1 id="title" class="clip" data-start="1" data-duration="4" data-track-index="1"> Formation Docker & Kubernetes </h1> <audio data-start="0" data-duration="6" data-track-index="2" data-volume="0.3" src="music.wav"></audio> <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script> <script> const tl = gsap.timeline({ paused: true }); tl.from("#title", { opacity: 0, y: 40, duration: 0.8 }, 1); window.__timelines = window.__timelines || {}; window.__timelines.intro = tl; </script> </div></code></pre> </div> </div> <div class="paragraph"> <p>무엇이 HyperFrames를 Remotion과 다르게 만드는가? React 없이, 없이 번들러, JSX 없이. AI 에이전트가 네이티브로 작성할 수 있는 순수한 HTML. 이건 <strong>정확히</strong> 내 파이프라인에 맞춰져 있습니다: planner-gradle와 deepseek와 함께 SPG/SPD 플랜에서 이 HTML을 생성할 수 있으며, Gradle 플러그인이 있습니다. MP4로 변환할 수 있다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_플러그인_아키텍처">플러그인 아키텍처</h2> <div class="sectionbody"> <div class="paragraph"> <p>hyperframes-gradle는 모든 플러그인과 동일한 패턴을 따릅니다: <a href="0124_architecture_plugin_gradle_racine_consommateur_independant_post.html">패턴 « 플러그인 indépendant + 소비자 루트 »</a></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">hyperframes-gradle/ ├── settings.gradle.kts ← racine consommateur (dogfood) ├── build.gradle.kts ← 3 lignes : apply plugin hyperframes ├── hyperframes-plugin/ ← BUILD INDÉPENDANT │ ├── gradlew ← son propre wrapper │ ├── build.gradle.kts ← java-gradle-plugin │ ├── src/main/kotlin/education/cccp/hyperframes/ │ │ ├── HyperframesPlugin.kt │ │ ├── GenerateHyperframesHtmlTask.kt │ │ ├── RenderHyperframesTask.kt │ │ └── HyperframesExtension.kt │ ├── .agents/ ← gouvernance agent │ └── doc/ │ └── HYPERFRAMES_ARCHITECTURE.adoc └── video.yml ← configuration dogfood</code></pre> </div> </div> <div class="sect2"> <h3 id="_네_단계_파이프라인">네 단계 파이프라인</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 11 title 파이프라인 hyperframes-gradle rectangle "AsciiDoc 소스" as adoc #LightYellow rectangle "AsciidoctorJ" as asciidoctorj #LightBlue rectangle "HTML HyperFrames (data-* 속성)" as html #LightGreen rectangle "HyperFrames CLI (Node.js 22+)" as cli #Lavender rectangle "video.mp4" as mp4 #Gold adoc -right-> asciidoctorj : parse blocs customs asciidoctorj -right-> html : génère HTML html -right-> cli : ProcessBuilder\nnpx hyperframes render cli -right-> mp4 : Puppeteer + FFmpeg @enduml</pre> </div> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>*AsciidoctorJ*는 AsciiDoc 소스를 파싱하고 사용자 지정 블록을 추출합니다.</p> </li> </ol> </div> <div class="paragraph"> <p><code>[hyperframes-composition]</code>, <code>[hyperframes-track]</code>, <code>[hyperframes-animation]</code>.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>GenerateHyperframesHtmlTask</strong> HTML HyperFrames과 함께 생성한다</p> </li> </ol> </div> <div class="paragraph"> <p>`data-*`해당하는 속성</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>*RenderHyperframesTask*는 HyperFrames CLI를 통해 호출합니다`ProcessBuilder`(empty)</p> </li> </ol> </div> <div class="paragraph"> <p><code>npx hyperframes render --input index.html --output video.mp4</code>.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>MP4는 …​에 배포됩니다`output/`와 함께`metadata.json`오케스트레이션을 위해.</p> </li> </ol> </div> </div> <div class="sect2"> <h3 id="_asciidoc_dsl">AsciiDoc DSL</h3> <div class="paragraph"> <p>플러그인의 진정한 추가 가치는 AsciiDoc DSL입니다. 사용자 그는 절대 HTML을 쓰지 않는다. 그는 기존의 AsciiDoc 문서에 주석을 단다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Formation Docker & Kubernetes :hyperframes-width: 1920 :hyperframes-height: 1080 :hyperframes-fps: 30 [hyperframes-composition, id="intro"] == Introduction Le titre apparaît avec un fondu GSAP sur fond vidéo. [hyperframes-track, index=0, start=0, duration=6] video::assets/background.mp4[muted, playsinline] [hyperframes-track, index=1, start=1, duration=4] Formation Docker & Kubernetes [hyperframes-animation, type=gsap]</code></pre> </div> </div> <div class="paragraph"> <p>const tl = gsap.timeline({ paused: true }); tl.from("#title", { opacity: 0, y: 40, duration: 0.8 }, 1); window.<em>timelines = window.</em>timelines || {}; window.__timelines.intro = tl;</p> </div> <div class="paragraph"> <p>docinfo 속성 (<code>:hyperframes-width:</code>) 치수를 설정합니다. 커스텀 블록은 구성 요소와 트랙을 정의합니다. 블록 `[hyperframes-animation]`원시 GSAP 코드가 포함되어 있습니다 — 에이전트 IA 자연어 설명에서 생성할 수 있다.</p> </div> </div> <div class="sect2"> <h3 id="_bridge_node_js">Bridge Node.js</h3> <div class="paragraph"> <p>유일한 기술적 마찰 지점: HyperFrames는 Node.js/TypeScript 기반입니다, 그리고 내 플러그인은 Kotlin/JVM입니다. 솔루션은`ProcessBuilder`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class RenderHyperframesTask : DefaultTask() { @TaskAction fun render() { val process = ProcessBuilder( "npx", "hyperframes", "render", "--input", inputHtml.absolutePath, "--output", outputMp4.absolutePath ) .inheritIO() .start() val exitCode = process.waitFor() require(exitCode == 0) { "HyperFrames render failed with exit code $exitCode" } } }</code></pre> </div> </div> <div class="paragraph"> <p>JVM 코드 ↔ Node.js 간 결합이 없습니다. 계약은 명령줄로 지정됩니다. 그리고 디스크의 파일들. 이것은 동일한 패턴이`plantuml-gradle` (PlantUML CLI를 호출하는) 또는`slider-gradle`(AsciidoctorJ를 호출하는). 해 아래에는 새로울 것이 없다 — 최신 도구에 적용된 것뿐이다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_두_개의_비디오_플러그인_두_가지_용도">두 개의 비디오 플러그인, 두 가지 용도</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.762%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">캡슐-gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">hyperframes-gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Source</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Deck reveal.js (기존 HTML)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">AsciiDoc → HTML 하이퍼프레임</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">사용 사례</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">복습 캡슐</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">독립형 설명 영상</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">자연</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Slides → 영상</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">문서 → 비디오</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">렌더링된</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Playwright 자바 → WebM</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">HyperFrames CLI → MP4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">애니메이션</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">전환 reveal.js 네이티브</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">GSAP/CSS 데이터 속성</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">스택</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">100% JVM (Kotlin)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">JVM + 외부 Node.js CLI</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>그들은 서로를 대체하지 않습니다. 서로를 보완합니다. 완전한 가치 사슬 :</p> </div> <div class="paragraph"> <p>AsciiDoc ──→ slider-gradle ──→ 덱 reveal.js ──→ capsule-gradle ──→ WebM (복습 캡슐)</p> </div> <div class="paragraph"> <p>AsciiDoc ──→ hyperframes-gradle ──→ MP4 (독립형 비디오)</p> </div> <div class="paragraph"> <p>사용자는 하나의 AsciiDoc 파일을 작성합니다. slider-gradle가 슬라이드를 생성합니다. capsule-gradle은 리뷰 캡슐을 만듭니다. hyperframes-gradle은 만듭니다 티저 영상과 기술 데모들</p> </div> </div> </div> <div class="sect1"> <h2 id="_로드맵의_6개_에픽">로드맵의 6개 에픽</h2> <div class="sectionbody"> <div class="paragraph"> <p>플러그인은 6개의 EPIC로 구성되어 있습니다 :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1682%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">서사시적인</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">설명</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">우선순위</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">HF-0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">부트스트랩 거버넌스 + 프레이밍 아키텍처</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ 끝났다</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">HF-1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Gradle 스텁 플러그인 + AsciidoctorJ 통합</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">P0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">HF-2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">브리지 CLI HyperFrames (ProcessBuilder → npx → MP4)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">P1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">HF-3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DSL AsciiDoc 관례 (블록, docinfo, 템플릿)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">P1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">HF-4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Gradle 러너 통합 (metadata.json)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">P2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">HF-5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">즉시 사용 가능한 템플릿 (title-card, code-diff, captions)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">P3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">HF-6</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">CI + Maven Central / Gradle Portal에 게시</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">P3</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>세션 000(bootstrap)는 이미 완료되었습니다. 세션 001은 HF-1을 공격할 것입니다: Gradle 플러그인 스텁과 AsciidoctorJ 통합.</p> </div> </div> </div> <div class="sect1"> <h2 id="_왜_동작하나요">왜 동작하나요?</h2> <div class="sectionbody"> <div class="paragraph"> <p>세 가지 이유:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>HyperFrames는 '에이전트를 위해 제작되었습니다'</strong>. 내 파이프라인은 AI 에이전트에 의존합니다.</p> </li> </ol> </div> <div class="paragraph"> <p>(planner-gradle + deepseek)가 콘텐츠를 생성합니다. HyperFrames는 받아들입니다. 원시 HTML — LLMs이 가장 잘 다루는 형식입니다. React이 없으며, 없음 JSX가 없으며, 에이전트에게 학습 곡선이 없습니다.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>AsciiDoc DSL은 자연스럽다</strong>. 내 생태계 전체가 AsciiDoc을 사용한다.</p> </li> </ol> </div> <div class="paragraph"> <p>slider-gradle, codex-gradle, training-gradle — 모두 소비하는`.adoc`. 사용자 정의 블록 추가`[hyperframes-composition]`확장입니다 논리적이다, 단절이 아니다</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Node.js 브릿지는 검증된 패턴입니다.</strong> JVM 외부의 ProcessBuilder,</p> </li> </ol> </div> <div class="paragraph"> <p>저는 이미 PlantUML, Graphviz, Piper에 대해 이것을 하고 있습니다. HyperFrames 추가 아키텍처에 아무것도 바꾸지 않는다 — 그것은 단지 외부 도구 하나 더일 뿐이다, Gradle에서 제어됨.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> <div class="paragraph"> <p>패턴의 진짜 힘은 npm 의존성이 없다는 점입니다 Gradle 빌드. 플러그인은 Node.js 코드를 가져오지 않습니다. 이를 실행 쉘 명령. HyperFrames가 진화하거나 깨지면, 플러그인은 결합되지 않습니다. — 명령어를 업데이트하기만 하면 됩니다.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_결론_잃어버린_고리">결론: 잃어버린 고리</h2> <div class="sectionbody"> <div class="paragraph"> <p>hyperframes-gradle와 함께, 내 비디오 파이프라인이 완성되었습니다. 저는 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>인터랙티브 슬라이드</strong> (slider-gradle)</p> </li> <li> <p><strong>수정 캡슐</strong> (캡슐-그레이들)</p> </li> <li> <p>그 <strong>standalone 비디오</strong> (hyperframes-gradle)</p> </li> </ul> </div> <div class="paragraph"> <p>세 가지 형식. 하나의 소스 파일: AsciiDoc.</p> </div> <div class="paragraph"> <p>다음 목표는 HF-1 : 플러그인을 컴파일하고 생성하는 것입니다. 주석이 달린 AsciiDoc 문서에서 첫 번째 HTML HyperFrames를 생성합니다. 세션 001은 이미 프레임이 잡혔습니다.</p> </div> <div class="paragraph"> <p>hyperframes-gradle가 존재해. 거버넌스가 마련되어 있어. 백로그 작성됨. 아키텍처가 문서화되었습니다. 플러그인이 탄생했습니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_참고문헌">참고문헌</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0124_architecture_plugin_gradle_racine_consommateur_independant_post.html">Article 0124 — 독립 플러그인 아키텍처 + 소비자 루트</a></p> </li> <li> <p><a href="https://github.com/heygen-com/hyperframes">HyperFrames — 깃허브</a></p> </li> <li> <p><a href="https://hyperframes.heygen.com/introduction">HyperFrames — 문서</a></p> </li> <li> <p><code>foundry/public/hyperframes-gradle/hyperframes-plugin/doc/HYPERFRAMES_ARCHITECTURE.adoc</code>— 상세한 아키텍처</p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0125_audit_conso_opencode_methodologie_comparaison_prix_llm_post.html Mon, 18 May 2026 00:00:00 +0000 blog/2026/0125_audit_conso_opencode_methodologie_comparaison_prix_llm_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_스택_이해하기_누가_무엇을_하는가">스택 이해하기: 누가 무엇을 하는가?</a></li> <li><a href="#_서론_왜_감사가_필요한가">서론: 왜 감사가 필요한가?</a></li> <li><a href="#_opencode_데이터베이스_금광">OpenCode 데이터베이스: 금광</a> <ul class="sectlevel2"> <li><a href="#_스키마">스키마</a></li> <li><a href="#_추출_코드">추출 코드</a></li> </ul> </li> <li><a href="#_결과_73일_소비">결과: 73일 소비</a> <ul class="sectlevel2"> <li><a href="#_전체_보기">전체 보기</a></li> <li><a href="#_모델_및_공급업체별_환기">모델 및 공급업체별 환기</a></li> <li><a href="#_세션_내_모델_세션_테이블이_보지_못하는_것">세션 내 모델 : 세션 테이블이 보지 못하는 것</a></li> </ul> </li> <li><a href="#_요금_비교_서구_공급업체">요금 비교 — 서구 공급업체</a> <ul class="sectlevel2"> <li><a href="#_anthropic_클로드">Anthropic — 클로드</a></li> <li><a href="#_openai_gpt">OpenAI — GPT</a></li> <li><a href="#_구글_제미니">구글 — 제미니</a></li> <li><a href="#_허깅페이스_추론_제공자">허깅페이스 추론 제공자</a></li> <li><a href="#_groq">Groq</a></li> </ul> </li> <li><a href="#_요금_비교_중국_공급업체">요금 비교 — 중국 공급업체</a> <ul class="sectlevel2"> <li><a href="#_deepseek_api_직접_platform_deepseek_com">DeepSeek API 직접 (platform.deepseek.com)</a></li> <li><a href="#_kimi_moonshot_platform_kimi_com">Kimi Moonshot (platform.kimi.com)</a></li> <li><a href="#_alibaba_bailian_bailian_aliyun_com">Alibaba Bailian (bailian.aliyun.com)</a></li> </ul> </li> <li><a href="#_요약_테이블_모든_제공자">요약 테이블 — 모든 제공자</a></li> <li><a href="#_숨은_비용_프롬프트_엔지니어링_및_반복">숨은 비용 : 프롬프트 엔지니어링 및 반복</a></li> <li><a href="#_ollama_cloud_pro_구독_누적_docker_방법">Ollama Cloud Pro 구독 누적 : Docker 방법</a></li> <li><a href="#_감사가_측정하지_않는_것">감사가 측정하지 않는 것</a></li> <li><a href="#_결론_숫자의_판결">결론 : 숫자의 판결</a></li> <li><a href="#_참조">참조</a> <ul class="sectlevel2"> <li><a href="#_요금_출처">요금 출처</a></li> </ul> </li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽기 시간: 22 minutes</div> <p>사람들은 종종 내 AI 사용량이 얼마나 비용이 드는지 자주 묻는다. 저는 '한 달에 20유로’라고 답하고, 사람들은 놀란 눈으로 저를 바라본다. 그렇다면 오늘, 저는 여러분께 검은 상자를 열어 보이겠다. 이 글은 나의 73일간의 바이브 코딩에 대한 종합 감사이다: OpenCode의 SQLite 데이터베이스에서 데이터를 추출하는 방법론, 테이블을 쿼리하는 SQL 코드, 그리고 시장의 모든 공급업체 — 서양과 중국을 포함한 — 에 대한 포괄적인 비교. 결과가 너무나 비대칭적이어서 나는 계산을 세 번 확인해야 했다.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">똑</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_스택_이해하기_누가_무엇을_하는가">스택 이해하기: 누가 무엇을 하는가?</h2> <div class="sectionbody"> <div class="paragraph"> <p>수자에 뛰어들기 전에 아키텍처를 명확히 합시다. 내 설정에는 세 가지 다른 행위자가 있으며, 그들을 혼동하지 않는 것이 중요합니다:</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 12 title 내 스택 LLM의 세 명의 배우 left to right direction actor "저 (개발자)" as Dev package "오픈코드 (github.com/anomalyco/opencode)" as OC { rectangle "vibe coding의 CLI 오픈 소스, 무료" as CLI note right of CLI C'est l'outil que j'utilise pour coder avec des agents IA. Il ne fournit AUCUN modèle. C'est un terminal + un orchestrateur. end note } package "Ollama (로컬 설치)" as OL { rectangle "추론 클라이언트 내 머신에 설치됨" as Client note right of Client C'est le logiciel qui fait tourner les modèles. Il peut les exécuter en local OU les déléguer au cloud selon le tag (:cloud). Il s'authentifie via clé SSH. end note } package "Ollama 클라우드 (ollama.com)" as OCloud { rectangle "클라우드 추론 서비스 프로 구독: 20€/월" as Cloud note right of Cloud C'est le fournisseur d'inférence. Mes modèles avec le tag :cloud sont exécutés sur LEURS serveurs. L'abonnement Pro donne accès à des quotas supérieurs. end note } Dev --> CLI : "프롬프트를 입력합니다" CLI --> Client : "이 모델을 불러" Client --> Cloud : "SSH 키 + 요청 (모델 :cloud)" Client --> Client : "로컬 실행 (클라우드가 없는 모델)" @enduml</pre> </div> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>OpenCode는 모델 제공자가 아닙니다.</strong>이것은 오픈 소스 CLI입니다 (<a href="https://github.com/anomalyco/opencode">github.com/anomalyco/opencode</a>) AI 에이전트를 오케스트레이션합니다. 구독을 판매하지 않으며, 추론을 제공하지 않습니다. 이것은의 동등물이다`git`버전 관리를 위한: 도구이지 서비스가 아닙니다. <strong>Ollama Cloud는 추론 제공업체입니다.</strong>내 로컬 Ollama 설치는 <strong>client</strong> 역할을 합니다 — 고유한 SSH 키(Device Key)를 통해 Ollama 서버에 인증하고, 태그가 지정된 모델의 실행을 그들에게 위임합니다.<code>:cloud</code>. 프로 구독(20유로/월)은 상위 할당량을 해제하고 Docker를 통해 동일한 머신에서 여러 계정을 통합할 수 있습니다.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_서론_왜_감사가_필요한가">서론: 왜 감사가 필요한가?</h2> <div class="sectionbody"> <div class="paragraph"> <p>두 달 전, 저는 로컬 Ollama 설치에서 모델을 무료로 사용하고 있었습니다. 그리고 저는 월 20유로에 첫 번째 Ollama Cloud Pro 구독을 시작했습니다. 이로 인해 클라우드 모델(태그가 있는`:cloud`) 제공업체를 통해`ollama-cloud`. 두 번째 구독이 한 달 후에 이어졌습니다, 별도의 Docker 인스턴스에서 자신의 계정과 자신의 SSH 키를 가진 — <a href="0120_cumuler_deux_abonnements_ollama_pro_docker_post.html">구독 누적에 대한 내 글</a>에서 설명한 누적 방법.</p> </div> <div class="paragraph"> <p>제가 고민하던 질문: <strong>이 20유로가 월마다 타당한가요 ?</strong> 직감으로가 아니라. 숫자로.</p> </div> <div class="paragraph"> <p>답변하기 위해서는 정확한 데이터가 필요했습니다. 추정이 아닙니다. 평균이 아닙니다. 나의 실제 <strong>소비</strong>, 토큰 단위로, 모델 단위로, 세션 단위로.</p> </div> <div class="paragraph"> <p>그리고 OpenCode — CLI — 는 이를 모두 SQLite 데이터베이스에 저장합니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_opencode_데이터베이스_금광">OpenCode 데이터베이스: 금광</h2> <div class="sectionbody"> <div class="paragraph"> <p>OpenCode는 세션 기록 전반를 SQLite 파일 안에 위치해 있는`~/.local/share/opencode/opencode.db`. La mienne pèse 660 Mo pour 73 jours d’utilisation — une base de données de production tout à fait respectable.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ls -lh ~/.local/share/opencode/opencode.db -rw-r--r-- 1 cheroliv cheroliv 660M mai 18 12:25 opencode.db</code></pre> </div> </div> <div class="sect2"> <h3 id="_스키마">스키마</h3> <div class="paragraph"> <p>베이스에는 약 20개의 테이블이 있지만, 그중 세 개는 우리 감사에 매우 중요합니다:</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 12 title 간소화된 스키마 — OpenCode SQLite entity "세션" as S { * id : TEXT -- * model : TEXT (JSON) * cost : REAL * tokens_input : INTEGER * tokens_output : INTEGER * tokens_reasoning : INTEGER * tokens_cache_read : INTEGER * tokens_cache_write : INTEGER * time_created : INTEGER * project_id : TEXT } entity "메시지" as M { * id : TEXT -- * session_id : TEXT <<FK>> * data : TEXT (JSON) * time_created : INTEGER } entity "프로젝트" as P { * id : TEXT -- * worktree : TEXT * name : TEXT } S ||--o{ M : "세션 아이디" S }o--|| P : "프로젝트_ID" note right of S La table session agrège tokens + coût + modèle. C'est notre point d'entrée principal. end note note right of M Les messages individuels. Le champ data contient le modèle utilisé (format JSON) même si la session change de modèle en cours de route. end note @enduml</pre> </div> </div> <div class="paragraph"> <p>테이블`session`전역 감사에 적합합니다 : 각 세션은 집계된 토큰 수, 사용된 모델, 그리고 비용을 가지고 있습니다. 필드`model`원시 JSON입니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{ "id": "deepseek-v4-pro:cloud", "providerID": "ollama-cloud", "variant": "default" }</code></pre> </div> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>필드`cost`OpenCode 데이터베이스에서는 *외부 API 요금*만 반영됩니다. 즉, API 키(Google Gemini, OpenAI 등)를 통해 사용량 기준으로 지불된 비용만 표시됩니다. Ollama을 통한 호출 — 로컬이든 Ollama Cloud Pro를 통해든 — 은 표시됩니다.`cost=0`비용이 정액제(구독)이기 때문에, 토큰당이 아닙니다. 이러한 호출의 실제 비용은 월간 구독료입니다.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_추출_코드">추출 코드</h3> <div class="paragraph"> <p>설치할 필요가 없습니다. Node.js 22+는 실험용 SQLite 모듈을 포함합니다 (<code>node:sqlite</code>) 완벽하게 작동합니다. 다음은 저에게 모든 것을 준 스크립트입니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">const { DatabaseSync } = require('node:sqlite'); const db = new DatabaseSync( `${process.env.HOME}/.local/share/opencode/opencode.db`, { readonly: true } ); // 1. Statistiques globales const global = db.prepare(` SELECT COUNT(*) as sessions, SUM(tokens_input) as total_input, SUM(tokens_output) as total_output, SUM(tokens_reasoning) as total_reasoning, SUM(tokens_cache_read) as total_cache_read, SUM(cost) as total_cost FROM session `).get(); // 2. Ventilation par modèle et fournisseur const byModel = db.prepare(` SELECT json_extract(model, '$.id') as model_id, json_extract(model, '$.providerID') as provider, COUNT(*) as sessions, SUM(tokens_input) as total_input, SUM(tokens_output) as total_output, SUM(cost) as total_cost FROM session WHERE model IS NOT NULL GROUP BY model_id, provider ORDER BY SUM(tokens_input) DESC `).all(); // 3. Par mois const monthly = db.prepare(` SELECT strftime('%Y-%m', datetime(time_created/1000, 'unixepoch')) as month, COUNT(*) as sessions, SUM(tokens_input) as total_input, SUM(tokens_output) as total_output, SUM(cost) as total_cost FROM session WHERE time_created IS NOT NULL GROUP BY month ORDER BY month `).all(); // 4. Messages par modèle (détection des changements intra-session) const msgByModel = db.prepare(` SELECT json_extract(m.data, '$.model.providerID') as provider, json_extract(m.data, '$.model.modelID') as model_id, COUNT(*) as messages FROM message m WHERE json_extract(m.data, '$.model') IS NOT NULL GROUP BY provider, model_id ORDER BY COUNT(*) DESC `).all(); console.log({ global, byModel, monthly, msgByModel }); db.close();</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> <div class="paragraph"> <p>플래그`--experimental-sqlite`Node.js 22.x에서 필요합니다. Node.js 24+에서는 모듈이 안정적이며 더 이상 플래그가 필요하지 않습니다.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_결과_73일_소비">결과: 73일 소비</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_전체_보기">전체 보기</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">미터법</th> <th class="tableblock halign-left valign-top">값</th> <th class="tableblock halign-left valign-top">맥락</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>세션 OpenCode</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1 022</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~14 세션/일 평균</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Tokens Input</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2.62억</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">그중 94.5백만 캐시 히트</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>토큰 출력</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">이천백만</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">안녕하세요</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Tokens Reasoning</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">141 000</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">무시할 만한 — 거의 생각 안 함</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>외부 API 비용</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>$0.22</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">구독 외 비용 (Gemini + 무료 등급)</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>이 \$0.22 수치는 중요한데, 이는 Ollama Cloud Pro 구독 외에 내가 추가로 지불한 모든 것을 나타냅니다. 즉 거의 없습니다. 구독이 필수 사항을 다 커버합니다.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 12 title 월간 진화 — 입력 토큰 rectangle "2026년 3월 9 세션 37,7M 토큰" as MARS #FFE082 rectangle "2026년 4월 486 세션 1.33억 토큰" as AVR #81C784 rectangle "2026년 5월 527 세션 12.5억 토큰" as MAI #64B5F6 MARS -right-> AVR : ×35 AVR -right-> MAI : stable (période en cours) note bottom of MAI Mai comptabilisé jusqu'au 18. Projection mois complet : ~2,1 Md tokens si la tendance se maintient. end note @enduml</pre> </div> </div> <div class="paragraph"> <p>3월과 4월 사이 증가량은 놀라웠습니다: 한 달 만에 35배 증가했습니다. 이는 '테스트' 사용에서 '운영' 사용으로의 전환점 — 즉, Gradle 플러그인을 위해 OpenCode 에이전트를 지속적으로 실행하기 시작했을 때입니다.</p> </div> </div> <div class="sect2"> <h3 id="_모델_및_공급업체별_환기">모델 및 공급업체별 환기</h3> <div class="paragraph"> <p>필드`model`테이블의`session`JSON인`json_extract()`깨끗하게 환기할 수 있습니다 :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 27.2727%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1819%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">모델 × 공급자</th> <th class="tableblock halign-left valign-top">세션</th> <th class="tableblock halign-left valign-top">입력</th> <th class="tableblock halign-left valign-top">Output</th> <th class="tableblock halign-left valign-top">비용</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">(No text provided to translate)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">63</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">220 M</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1,94 M</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">deepseek-v4-pro @ ollama-b</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">124</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">463 M</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">4,15 M</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">deepseek-v4-pro @ ollama</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">100</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">252 M</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2,25 M</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">deepseek-v4-flash-free @ opencode</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">16</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1,3 M</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">279 K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">qwen3.6-plus-free @ opencode</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">369 K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">25 K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">gemini-2.5-flash @ 구글</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">211 K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">19 K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,04</p></td> </tr> </tbody> </table> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>세 가지 다른 공급자, 정확히 같은 DeepSeek V4 Pro 모델 : * <code>ollama-cloud</code>→ 통해서 <strong>유료 Pro 구독</strong> (Ollama가 관리하는 클라우드) * <code>ollama-b</code>→ <strong>두 번째 Pro 구독</strong>, 별도의 Docker 컨테이너에 격리됨 * <code>ollama</code>→ 현지 로캘 인스턴스, <strong>gratuite</strong> (내 기계에서 직접 실행됨) 세 가지의 합은 936M 입력, 8,4M 출력 — 이것이 DeepSeek V4 Pro의 총 소비량이며, 모든 제공업체를 합친 것입니다. 오직`ollama-cloud`(220M 입력)에는 구독료가 발생합니다. 남은 716M은 무료입니다 (로컬 또는 구독 누적).</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_세션_내_모델_세션_테이블이_보지_못하는_것">세션 내 모델 : 세션 테이블이 보지 못하는 것</h3> <div class="paragraph"> <p>테이블`session`주요 모델 *principal*만 세션을 캡처합니다. 하지만 동일한 세션 동안 OpenCode 에이전트는 여러 모델 간에 전환할 수 있습니다. 테이블`message`보여준다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">Modèles utilisés dans les messages (ollama-cloud provider) : ├─ deepseek-v4-pro 1 441 msgs (32%) ├─ qwen3.5:397b 1 217 msgs (27%) ├─ glm-5.1 712 msgs (16%) ├─ kimi-k2.6:cloud 634 msgs (14%) ├─ qwen3-coder:480b 414 msgs (9%) ├─ gpt-oss:20b 34 msgs (0,8%) ├─ qwen3-coder-next 27 msgs (0,6%) └─ gemma4:31b 7 msgs (0,2%)</code></pre> </div> </div> <div class="admonitionblock caution"> <table> <tr> <td class="icon"> <i class="fa icon-caution" title="🔒"></i> </td> <td class="content"> <div class="paragraph"> <p>이제 Qwen, GLM, Kimi 그리고 다른 모델들을 더 사용하지 않습니다. 그것들은 4월에 꽤 많은 것을 테스트했기 때문에 기록에 나타납니다. 5월 중순부터 저는 DeepSeek V4 Pro에 잠겨 있습니다 — 이것이 긴 컨텍스트에서 에이전트 거버넌스와 함께 부하를 견딜 수 있는 유일한 모델입니다 (cf. <a href="0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html">나의 Kimi/GLM/DeepSeek 비교</a>). 히스토리에서의 deepseek 메시지 32%는 오해를 일으킵니다: 오늘은 100%입니다.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_요금_비교_서구_공급업체">요금 비교 — 서구 공급업체</h2> <div class="sectionbody"> <div class="paragraph"> <p>불편한 질문 : 전통적인 공급업체에서 이 같은 소비는 얼마가 들까?</p> </div> <div class="paragraph"> <p>비교를 위한 나의 계산 기준 :<strong>220M 토큰 입력 + 1,9M 토큰 출력</strong>— <strong>uniquement</strong> 통과된 볼륨`ollama-cloud`(내가 유료 구독과 일치하는 유일한 것). 나머지 716M은 무료입니다 (Ollama 로컬 및 Docker B 인스턴스).</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 23.0769%;"> <col style="width: 15.3846%;"> <col style="width: 15.3846%;"> <col style="width: 15.3846%;"> <col style="width: 15.3846%;"> <col style="width: 15.3847%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">공급업체</th> <th class="tableblock halign-left valign-top">모델</th> <th class="tableblock halign-left valign-top">$/M</th> <th class="tableblock halign-left valign-top">출력 \$/M</th> <th class="tableblock halign-left valign-top">비용/월</th> <th class="tableblock halign-left valign-top">× 내 구독</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">내 설정</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek V4 Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\~20€</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>1×</strong></p></td> </tr> </tbody> </table> <div class="sect2"> <h3 id="_anthropic_클로드">Anthropic — 클로드</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 27.2727%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1819%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">모델</th> <th class="tableblock halign-left valign-top">$/M</th> <th class="tableblock halign-left valign-top">출력 \$/M</th> <th class="tableblock halign-left valign-top">월 비용</th> <th class="tableblock halign-left valign-top">× 내 구독</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Opus 4.7</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$25</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1 148</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>57×</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">소네트 4.6</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$15</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$689</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>34×</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Haiku 4.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$230</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>11×</strong></p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Haiku 4.5, Claude의 가장 '경제적인' 모델조차 내 구독료의 11배에 해당한다. 게다가 내 코드베이스를 전혀 알지 못하며, 내 스타일로 생성하지도 못하고, Gradle Kotlin DSL API에 대해 환각을 일으킨다.</p> </div> </div> <div class="sect2"> <h3 id="_openai_gpt">OpenAI — GPT</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 27.2727%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1819%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">모델</th> <th class="tableblock halign-left valign-top">$/M</th> <th class="tableblock halign-left valign-top">$/M</th> <th class="tableblock halign-left valign-top">월 비용</th> <th class="tableblock halign-left valign-top">× 내 구독</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$30</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1 157</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>58×</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$2,50</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$15</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$579</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>29배</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.4 미니</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,75</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$4,50</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$174</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>9배</strong></p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_구글_제미니">구글 — 제미니</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 27.2727%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1819%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">모델</th> <th class="tableblock halign-left valign-top">$/M</th> <th class="tableblock halign-left valign-top">출력 $/M</th> <th class="tableblock halign-left valign-top">비용/월</th> <th class="tableblock halign-left valign-top">× 내 구독</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">제미니 3.1 프로</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$2,00</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$10</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$459</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>23×</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">제미나이 3 플래시</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,30</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1,50</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$69</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>3.5×</strong></p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Gemini 3 Flash 69€는 순수 가격 기준으로 유일한 근접 경쟁자 — 하지만 이는 가볍고 밀도가 높은 모델이지, DeepSeek V4 Pro 같은 1.6T MoE 모델이 아닙니다. 생성된 코드의 품질과는 전혀 관련이 없습니다.</p> </div> </div> <div class="sect2"> <h3 id="_허깅페이스_추론_제공자">허깅페이스 추론 제공자</h3> <div class="paragraph"> <p>HuggingFace 자체적으로 추론을 수행하지 않으며 — 제3자 <strong>providers</strong> (Novita, Together, DeepInfra, Cerebras, SambaNova, Fireworks, Groq…)를 통합된 API를 통해 집계합니다. 가장 저렴하거나 가장 빠른 provider를 선택합니다. 다음은 2026년 5월에 확인된 DeepSeek V4 Pro의 요금입니다 :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 27.2727%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1819%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">제공자 HF</th> <th class="tableblock halign-left valign-top">달러/미터</th> <th class="tableblock halign-left valign-top">$/M</th> <th class="tableblock halign-left valign-top">월 비용</th> <th class="tableblock halign-left valign-top">× 내 구독</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Novita (가장 저렴한)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1,67</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$3,38</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>$374</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>19배</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">딥인프라</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1,74</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$3,48</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>389달러</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>19×</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">함께</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$2,10</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$4,40</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>470달러</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>23×</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">파이어워크스</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">비공개 요금</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>HuggingFace에서 가장 저렴한 제공업체(Novita)조차도 내 구독료의 19배를 청구합니다. 그리고 Ollama Cloud와 달리, HuggingFace는 PRO HF 구독이 없을 경우(월 \$9) 플랫폼 이용료도 추가로 청구합니다.</p> </div> </div> <div class="sect2"> <h3 id="_groq">Groq</h3> <div class="paragraph"> <p>Groq에는 제가 사용하는 모델이 <strong>아예</strong> 하나도 없습니다 — 그들의 카탈로그는 GPT-OSS, Llama, Qwen 32B로 제한됩니다. 비교할 수 없습니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_요금_비교_중국_공급업체">요금 비교 — 중국 공급업체</h2> <div class="sectionbody"> <div class="paragraph"> <p>진정한 테스트는 중국 시장이다. DeepSeek이 중국 모델이라면, 그 네이티브 API는 더 저렴해야 하지 않나요?</p> </div> <div class="sect2"> <h3 id="_deepseek_api_직접_platform_deepseek_com">DeepSeek API 직접 (platform.deepseek.com)</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 22.2222%;"> <col style="width: 22.2222%;"> <col style="width: 22.2223%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">기간</th> <th class="tableblock halign-left valign-top">$/M</th> <th class="tableblock halign-left valign-top">출력 \$/M</th> <th class="tableblock halign-left valign-top">비용/월</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">프로모션 -75% (5월 31일까지)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,435</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,87</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>$98</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">정상 요금 (6월부터)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1,74</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$3,48</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>390달러</strong></p></td> </tr> </tbody> </table> <div class="paragraph"> <p>DeepSeek의 공격적인 프로모션(-75% 연장)에도 불구하고 직접 API 비용이 듭니다.<strong>5×</strong>더 비싸다. 정상 요금으로는<strong>20배</strong>. 그것이 DeepSeek만 — 다른 모델에 접근할 수 없습니다.</p> </div> </div> <div class="sect2"> <h3 id="_kimi_moonshot_platform_kimi_com">Kimi Moonshot (platform.kimi.com)</h3> <div class="paragraph"> <p>Kimi는 자신의 모델만 제안합니다. DeepSeek 없습니다.</p> </div> </div> <div class="sect2"> <h3 id="_alibaba_bailian_bailian_aliyun_com">Alibaba Bailian (bailian.aliyun.com)</h3> <div class="paragraph"> <p>중국 모델을 모두 집계하는 유일한 공급자 — 하지만 마진을 붙여 재판매를 통해. 가격은 자바스크립트를 통해 동적으로 로드되어 스크래핑이 불가능하게 된다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_요약_테이블_모든_제공자">요약 테이블 — 모든 제공자</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 23.0769%;"> <col style="width: 15.3846%;"> <col style="width: 15.3846%;"> <col style="width: 15.3846%;"> <col style="width: 15.3846%;"> <col style="width: 15.3847%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">공급자</th> <th class="tableblock halign-left valign-top">모델</th> <th class="tableblock halign-left valign-top">$/M</th> <th class="tableblock halign-left valign-top">출력 \$/M</th> <th class="tableblock halign-left valign-top">월 비용</th> <th class="tableblock halign-left valign-top">× 나의 구독</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ollama Cloud Pro</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek V4 Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>~20유로</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>1×</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">제미니 3 플래시</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">제미니 3 플래시</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,30</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1,50</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$69</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3,5×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek API (프로모)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek V4 Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,44</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,87</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$98</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">5×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.4 미니</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.4 미니</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,75</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$4,50</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$174</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">9×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Claude Haiku 4.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Claude Haiku 4.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$230</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">11×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">HuggingFace/Novita</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">딥시크 V4 프로</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1,67</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$3,38</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$374</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">19×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek API (일반)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">딥시크 V4 프로</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1,74</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$3,48</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$390</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">20×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">함께 AI</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek V4 Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$2,10</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$4,40</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$470</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">23×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$2,50</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$15</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$579</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">29×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Claude Sonnet 4.6</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">클로드 소네트 4.6</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$15</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$689</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">34×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Claude Opus 4.7</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Claude Opus 4.7</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$25</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1 148</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">57×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$30</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1 157</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">58×</p></td> </tr> </tbody> </table> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 11 title 예상 월간 비용 — 220M 입력 + 1.9M 출력 rectangle "Ollama Cloud Pro ~20€" as OC #4CAF50 rectangle "제미니 플래시 69달러" as GF #8BC34A rectangle "DeepSeek 프로모션 $98" as DSP #FFC107 rectangle "GPT Mini \$174" as GM #FF9800 rectangle "클로드 하이쿠 \$230" as CH #FF5722 rectangle "HF/Novita $374" as HF #F44336 rectangle "DeepSeek 일반 \$390" as DSN #F44336 rectangle "GPT 5.4\n\$579" as G4 #D32F2F rectangle "Claude Sonnet \$689" as CS #D32F2F rectangle "Claude Opus $1 148" as CO #B71C1C rectangle "GPT 5.5\n\$1 157" as G5 #880E4F note bottom of OC DeepSeek V4 Pro 1.6T MoE + accès à tout le catalogue Ollama Cloud (Qwen, GLM, Kimi...) Inclus dans l'abonnement end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_숨은_비용_프롬프트_엔지니어링_및_반복">숨은 비용 : 프롬프트 엔지니어링 및 반복</h2> <div class="sectionbody"> <div class="paragraph"> <p>토큰 비용은 방정식의 일부일 뿐입니다. 진짜 비용은 개발자 시간입니다.</p> </div> <div class="paragraph"> <p>OpenCode + Ollama Cloud Pro + 내 거버넌스 에이전트(EAGER/LAZY/Hot/Warm/Cold, <a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">거버넌스에 대한 문서</a>)를 사용하면 다음과 같은 결과를 얻습니다:</p> </div> <div class="ulist"> <ul> <li> <p><strong>0 반복적인 프롬프트 엔지니어링</strong>컨텍스트가 자동으로 주입됩니다.</p> </li> <li> <p><strong>90%+ first-shot correct</strong>: 코드가 처음에 컴파일됩니다</p> </li> <li> <p><strong>연속 8회 세션에서 딥시크 환각 제로</strong>(문서화된 <a href="0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html">Kimi/GLM/DeepSeek 비교</a>)</p> </li> </ul> </div> <div class="paragraph"> <p>Claude 혹은 GPT 미세 조정 없이 거버넌스 없이 :</p> </div> <div class="ulist"> <ul> <li> <p>작업당 평균 2-3번의 반복</p> </li> <li> <p>체계적인 프롬프트 엔지니어링</p> </li> <li> <p>컨텍스트가 30K 토큰을 초과하면 Kotlin/Gradle API에 대한 환각이 발생합니다.</p> </li> </ul> </div> <div class="paragraph"> <p>월간 « 효과적 » 비용 — 토큰 × 반복 횟수 × 수정 시간 — 은 내 솔루션의 비용의 27배에서 54배이며, 이는 <a href="0122_ratio_efficacite_27x_45x_flotte_experts_ia_vs_claude_gpt_post.html">l’article sur le ratio d’efficacité</a>에서 입증한 바와 같다.</p> </div> <div class="paragraph"> <p><em><em>_ 토큰당 가격 문제에 그치는 것이 아니다. 가격이 57배인 Claude Opus이면서 3배 더 많은 반복이 필요한 경우, 실질적인 비용은 약 170배 더 높다. 솔직히 말해, 인턴에게 맥킨지 파트너 급여를 지불하는 것과 같다. </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_ollama_cloud_pro_구독_누적_docker_방법">Ollama Cloud Pro 구독 누적 : Docker 방법</h2> <div class="sectionbody"> <div class="paragraph"> <p>한 개의 구독만으로는 충분하지 않을 때, 이를 여러 개 결합합니다. 원칙은 각 구독을 자체 Ollama 설치 및 자체 SSH 인증 키로 분리하는 것입니다. Docker는 이를 간단하게 만듭니다.</p> </div> <div class="paragraph"> <p>전체 방법은 <a href="0120_cumuler_deux_abonnements_ollama_pro_docker_post.html">도커 누적 문서</a>에 자세히 나와 있습니다. 다음은 원칙입니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 12 title 아키텍처 — 한 머신에서 두 개의 Ollama Cloud Pro 구독 left to right direction node "내 물리적 기계" { frame "Ollama 인스턴스 A (네이티브) 포트 :11434" as Native { database "정체성 A /usr/share/ollama/.ollama/id_ed25519" } frame "Ollama 인스턴스 B (Docker) 포트 :11435" as Docker { database "Identité B\n~/ollama-b-data/id_ed25519" } } cloud "올라마 클라우드" { actor "계정 프로 A\n(이메일 1)" as A actor "프로 B 계정 (이메일 2)" as B } Native --> A : "디바이스 키 A" Docker --> B : "디바이스 키 B" note bottom of Docker Conteneur Docker isolé : - Clé SSH distincte - Port réseau distinct (11435) - Volume persistant (~/ollama-b-data) - restart: always end note @enduml</pre> </div> </div> <div class="paragraph"> <p>패턴은 간단합니다 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>볼륨 만들기`~/ollama-b-data`</p> </li> <li> <p>Docker 컨테이너 실행`ollama/ollama:0.20.2`에 매핑된`11435:11434`</p> </li> <li> <p>컨테이너의 SSH 키를 가져오기 → ollama.com에 저장하기</p> </li> <li> <p>하다`ollama signin`두 번째 이메일과 함께</p> </li> <li> <p>두 개의 공급자와 OpenCode 구성하기 (`ollama`에서 :11434,`ollama-b`에 :11435)</p> </li> </ol> </div> <div class="paragraph"> <p>두 개의 계좌, 하나의 파란색 카드, 갈등이 없습니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_감사가_측정하지_않는_것">감사가 측정하지 않는 것</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 40%;"> <col style="width: 60%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">사각지대</th> <th class="tableblock halign-left valign-top">영향</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>생산된 코드 품질</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">26억 개의 토큰은 코드가 컴파일되는지 여부를 말하지 않는다. 내 DeepSeek V4 Pro 8회 세션의 first-shot 성공률은 90%를 초과한다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>OpenCode 생태계</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">CLI는 무료이지만, 그 가치(에이전트, 샌드박스, 기록, 프롬프트 캐싱)는 엄청납니다. 구독 가격에 포함되지 않았습니다 — 별도의 도구입니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>기회 비용</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">하루에 2시간을 저급 모델의 환각을 디버깅하는 데 쓰면 월 20유로보다 더 비싸다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>마음의 평화</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">정액 요금 = 놀라움 없음. 토큰당 과금 방식에서는 활동량이 급증하면 큰 타격을 입을 수 있다.</p></td> </tr> </tbody> </table> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="⚠️"></i> </td> <td class="content"> <div class="paragraph"> <p>인용된 가격은 2026년 5월의 가격입니다. 6개월 후에는 모든 것이 하락할 것입니다. 하지만 구조적인 힘의 균형 — 고정 구독 대비 종량제 — 은 대량 소비자에게 여전히 구독이 유리할 것이다.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_결론_숫자의_판결">결론 : 숫자의 판결</h2> <div class="sectionbody"> <div class="paragraph"> <p>73일 후, 1,022회 OpenCode 세션, 그리고 26억 토큰 :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 60%;"> <col style="width: 40%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">미터법</th> <th class="tableblock halign-left valign-top">판결</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">외부 API 누적 비용</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>$0.22</strong>(거의 0)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Ollama Cloud Pro 구독 비용</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>~20유로/월</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Claude Opus의 동등물</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>$1 148/월</strong>— 57배 더 비싸다</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.5와 동등한</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>$1,157/월</strong>— 58배 더 비쌈</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">해당하는 HuggingFace/Novita</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\$374/mois</strong>— 19× 더 비싼</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">동등한 DeepSeek API 직접</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>$390/월</strong>— 20배 더 비싸다</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">가장 저렴한 등가물 (Gemini Flash)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>$69/개월</strong>— 3,5× 더 비싼, 하위 모델</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>시장에서 최고의 제안</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ollama Cloud Pro 월 20유로</strong>— 무적의</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><em>__</em> 월 20유로에 Ollama Cloud를 통해 DeepSeek V4 Pro(1.6T 파라미터, MoE, CSA+HCA, 1M 컨텍스트)에 접속하면 세계 시장에서 가장 좋은 가성비를 누릴 수 있습니다. 중국 공급업체와 직접 거래해도 5배에서 20배 더 비쌉니다. 저비용 제공업체 집계를 통해 서비스하는 HuggingFace조차도 19배 더 비쌉니다. 서구 시장(Claude, GPT)은 50-60배 더 비싸며, 이는 마치 다른 행성과 같습니다.</p> </div> <div class="paragraph"> <p>이 비율은 너무 불균형해서 영원히 지속될 수 없습니다. 존재하는 동안 이를 활용하세요. <em>__</em></p> </div> <div class="paragraph"> <p>그렇다면, 월 20유로는 내 개발자 생활에서의 최고의 기술적 투자다. 그리고 이제 당신은それを 입증할 수 있는 수치가 있습니다.</p> </div> <hr> </div> </div> <div class="sect1"> <h2 id="_참조">참조</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">Article 0108 — 거버넌스 에이전트 EAGER/LAZY/Hot/Warm/Cold</a></p> </li> <li> <p>문서 0112 — DeepSeek V4 Pro 대 Kimi K2.6 대 GLM 5.1</p> </li> <li> <p><a href="0119_benchmark_dgx_spark_vs_cloud_abonnement_llm_post.html">문서 0119 — DGX Spark vs Cloud vs LLM 구독 벤치마크</a></p> </li> <li> <p><a href="0120_cumuler_deux_abonnements_ollama_pro_docker_post.html">문서 0120 — Ollama Cloud Pro와 Docker용 두 구독 결합</a></p> </li> <li> <p><a href="0121_plugin_gradle_piloter_deux_instances_ollama_pro_post.html">문서 0121 — Ollama 두 인스턴스를 제어하는 Gradle 플러그인</a></p> </li> <li> <p><a href="0122_ratio_efficacite_27x_45x_flotte_experts_ia_vs_claude_gpt_post.html">문서 0122 — 효율 비율 27배에서 54배</a></p> </li> </ul> </div> <div class="sect2"> <h3 id="_요금_출처">요금 출처</h3> <div class="ulist"> <ul> <li> <p><a href="https://ollama.com/pricing">Ollama Cloud — Pro 요금 \$20/개월</a></p> </li> <li> <p><a href="https://api-docs.deepseek.com/quick_start/pricing">DeepSeek API — 공식 요금 V4 Pro</a></p> </li> <li> <p><a href="https://platform.kimi.com/docs/pricing/chat-k26">Kimi Moonshot — 가격 K2.6</a></p> </li> <li> <p><a href="https://huggingface.co/inference/models">HuggingFace Inference Providers — 제공업체별 요금</a></p> </li> <li> <p><a href="https://www.anthropic.com/pricing">Anthropic — Claude API 요금</a></p> </li> <li> <p><a href="https://openai.com/api/pricing/">OpenAI — GPT API 요금</a></p> </li> <li> <p><a href="https://together.ai/pricing">Together AI — 추론 요금</a></p> </li> <li> <p><a href="https://groq.com/pricing">Groq — API 요금</a></p> </li> <li> <p><a href="https://deepinfra.com/pricing">DeepInfra — GPU 요금 및 모델</a></p> </li> <li> <p><a href="https://help.aliyun.com/zh/model-studio/text-generation-model/">Alibaba Bailian — 사용 가능한 모델</a></p> </li> <li> <p><a href="https://github.com/anomalyco/opencode">OpenCode — GitHub 오픈 소스 CLI</a></p> </li> </ul> </div> </div> </div> </div> https://cheroliv.com/blog/2026/0124_architecture_plugin_gradle_racine_consommateur_independant_post.html Thu, 14 May 2026 00:00:00 +0000 blog/2026/0124_architecture_plugin_gradle_racine_consommateur_independant_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_문제_내_시간을_잡아먹은_세_가지_아키텍처">문제: 내 시간을 잡아먹은 세 가지 아키텍처</a> <ul class="sectlevel2"> <li><a href="#_option_1_분리된_플러그인_dogfooding_안_함">Option 1 : 분리된 플러그인 (Dogfooding 안 함)</a></li> <li><a href="#_옵션_2_클래식_모노레포_includeplugin">옵션 2 : 클래식 모노레포 (<code>include(":plugin")</code>)</a></li> <li><a href="#_옵션_3_컴포지트_빌드_includebuild">옵션 3 : 컴포지트 빌드 (<code>includeBuild()</code>)</a></li> </ul> </li> <li><a href="#_해결책_독립된_두_개의_빌드_소비자_루트">해결책: 독립된 두 개의 빌드, 소비자 루트</a> <ul class="sectlevel2"> <li><a href="#_워크플로우">워크플로우</a></li> <li><a href="#_구체적인_워크플로">구체적인 워크플로</a></li> </ul> </li> <li><a href="#_왜_이_아키텍처가_나를_사로잡았는가">왜 이 아키텍처가 나를 사로잡았는가?</a> <ul class="sectlevel2"> <li><a href="#_1_네이티브_도그푸딩_즉각적인_피드백">1. 네이티브 도그푸딩, 즉각적인 피드백</a></li> <li><a href="#_2_제로_콘피그_클로닝">2. 제로-콘피그 클로닝</a></li> <li><a href="#_3_격리된_빌드_독립된_ci">3. 격리된 빌드, 독립된 CI</a></li> </ul> </li> <li><a href="#_서브_폴더의_해부학_name_plugin">서브 폴더의 해부학 `{name}-plugin/</a> <ul class="sectlevel2"> <li><a href="#_버전_카탈로그_두_개의_별도_파일">버전 카탈로그 : 두 개의 별도 파일</a></li> </ul> </li> <li><a href="#_우리가_하지_않는_것">우리가 하지 않는 것</a></li> <li><a href="#_비교_세_가지_아키텍처가_마주하는_도그푸딩">비교 : 세 가지 아키텍처가 마주하는 도그푸딩</a></li> <li><a href="#_dag_계약_루트_빌드는_하위_폴더에서_절대_가져오지_않는다">DAG 계약: 루트 빌드는 하위 폴더에서 절대 가져오지 않는다.</a></li> <li><a href="#_결론_시간을_절약해_주는_겉보기상의_중복">결론 : 시간을 절약해 주는 겉보기상의 중복</a></li> <li><a href="#_참고문헌">참고문헌</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽기 시간 : 11 minutes</div> <p>Gradle 플러그인 저장소를 복제합니다. 터미널을 엽니다. 무엇을 입력하시나요? 그리고?<code>./gradlew tasks</code>, 물론이죠. 하지만 어느 폴더인가요? 루트 폴더인가요? 서브모듈 폴더인가요? 먼저 README를 읽어야 builder 방법을 알 수 있나요? 주저한다면 그저 한 초일 뿐인데, 프로젝트 아키텍처가 깨졌습니다.</p> </div> <div class="paragraph"> <p>다음은 제가 이 문제를 완전히 해결한 방법 — 그리고 왜 이 패턴은 오늘날 내 모든 Gradle 플러그인의 서명인`foundry/public/`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_문제_내_시간을_잡아먹은_세_가지_아키텍처">문제: 내 시간을 잡아먹은 세 가지 아키텍처</h2> <div class="sectionbody"> <div class="paragraph"> <p>현재 패턴에 수렴하기 전에, 나는 세 가지 접근 방식 사이에서 헤맸다. Gradle 플러그인을 구성하는 전통적인 방법들마다 치명적인 결함이 있었다.</p> </div> <div class="sect2"> <h3 id="_option_1_분리된_플러그인_dogfooding_안_함">Option 1 : 분리된 플러그인 (Dogfooding 안 함)</h3> <div class="paragraph"> <p>프로젝트에는 플러그인만 포함되어 있습니다. 소비 예시가 없습니다. 없음 프로젝트가 그것을 수행한다. 테스트하려면 외부 프로젝트를 만들어야 합니다, y 를 통해 플러그인을 참조하다`mavenLocal`또는 복합 빌드, 그리고 단지 거기서 그것이 작동하는지 확인하다</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-shell hljs" data-lang="shell">$ git clone mon-plugin $ cd mon-plugin $ ./gradlew build # le plugin compile $ # ... et maintenant ? comment je l'essaie ?</code></pre> </div> </div> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="⚠️"></i> </td> <td class="content"> <div class="paragraph"> <p>소비 예시가 없는 Gradle 플러그인은 소비 예시가 없는 라이브러리다 통합 테스트. 마지막 수정이 무엇인지 결코 알 수 없습니다. 사용자 경험을 깨뜨렸습니다.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_옵션_2_클래식_모노레포_includeplugin">옵션 2 : 클래식 모노레포 (<code>include(":plugin")</code>)</h3> <div class="paragraph"> <p>Gradle`init`생성합니다`settings.gradle.kts`와 함께`include("plugin")`. 루트와 서브모듈은 같은 데몬과 동일한 구성을 공유합니다, 같은 카탈로그들. 편리하지만 결합된.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">. ├── settings.gradle.kts → include("plugin") ├── build.gradle.kts → plugins { id("mon-plugin") } ├── plugin/ │ └── build.gradle.kts → java-gradle-plugin └── gradle/ └── libs.versions.toml</code></pre> </div> </div> <div class="paragraph"> <p>문제점:</p> </div> <div class="ulist"> <ul> <li> <p>루트<strong>해야 한다</strong>서브 모듈과 동일한 Gradle 버전을 가지고 있다.</p> </li> <li> <p>`libs.versions.toml`공유됨—공통 버전 카탈로그, 의존성</p> </li> </ul> </div> <div class="paragraph"> <p>하나의 모듈에서 다른 모듈로 도망치는.</p> </div> <div class="ulist"> <ul> <li> <p>플러그인을 루트와 독립적으로 빌드할 수 없습니다.</p> </li> <li> <p>CI는 두 모듈을 모두 빌드해야 하며, 플러그인만 변경된 경우에도 마찬가지입니다.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_옵션_3_컴포지트_빌드_includebuild">옵션 3 : 컴포지트 빌드 (<code>includeBuild()</code>)</h3> <div class="paragraph"> <p>우리는 두 개를 별도의 Gradle 빌드로 분리하고 이를 통해 연결합니다. <code>includeBuild("mon-plugin")`안에`settings.gradle.kts</code>.</p> </div> <div class="paragraph"> <p>이미 더 나아졌습니다. 플러그인 빌드가 격리되었습니다. 하지만 소비자 외부 빌드를 명시적으로 참조해야 한다 — 출력의 `./gradlew tasks`루트에서 의 올바른 구성에 따라 달라집니다 복합체. 복제는 zero-config이 아니다: 알아야 할 점은 플러그인은 별도의 폴더에 위치하고, 루트가 이를 참조합니다 등.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-shell hljs" data-lang="shell">. ├── settings.gradle.kts → includeBuild("plugin-build/") ├── build.gradle.kts → plugins { id("mon-plugin") } └── plugin-build/ ├── settings.gradle.kts └── build.gradle.kts</code></pre> </div> </div> <div class="paragraph"> <p>나는 더 나은 것을 찾고 있었어. 훨씬 더 나은 것을.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_해결책_독립된_두_개의_빌드_소비자_루트">해결책: 독립된 두 개의 빌드, 소비자 루트</h2> <div class="sectionbody"> <div class="paragraph"> <p>제가 결국 채택한 패턴은 다음과 같습니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">. ├── settings.gradle.kts ← racine consommateur ├── build.gradle.kts ← 3 lignes : apply plugin + dogfood ├── gradle/ │ └── libs.versions.toml ← catalogue du consommateur ├── {name}-plugin/ ← BUILD INDÉPENDANT │ ├── gradlew ← son propre wrapper │ ├── settings.gradle.kts ← rootProject.name = "{name}-plugin" │ ├── build.gradle.kts ← java-gradle-plugin, signing, publish │ ├── gradle/ │ │ ├── libs.versions.toml ← catalogue du plugin │ │ └── wrapper/ │ ├── src/ ← sources du plugin │ ├── .agents/ ← gouvernance agent │ └── *.adoc ← AGENT, PROMPT_REPRISE, snapshot, etc. └── site.yml / slides-context.yml / ... ← configs dogfood</code></pre> </div> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>키 :`{name}-plugin/`는 <strong>완전하고 독립적인</strong> Gradle 프로젝트입니다. 그는 자체 wrapper, 자체 settings, 자체 카탈로그 de를 가지고 있습니다. 버전. 그것은 클론되고, 빌드되고, 테스트되고, 게시되며, 루트 없이 존재를 알고 있어야 합니다.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>루트는 오직 '<strong>une</strong>' 일만 한다: 플러그인을 적용한다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">plugins { alias(libs.plugins.bakery) } repositories { mavenLocal() mavenCentral() } bakery { configPath = file("site.yml").absolutePath }</code></pre> </div> </div> <div class="paragraph"> <p>경우에 따라 세 줄`bakery-gradle`. 그만입니다. 제로`include()<code>, 영`includeBuild()</code>, 제로 하위 프로젝트. 어떤 플러그인을 적용하는 것처럼 일반적인 Gradle 빌드 어떤 소비자가それを 할까요?</p> </div> <div class="sect2"> <h3 id="_워크플로우">워크플로우</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 12 left to right direction package "루트 (소비자)" #CCFFCC { usecase "저장소를 복제" as Clone usecase "./gradlew 작업" as Tasks usecase "./gradlew bake" as Dogfood note bottom of Dogfood Exerce le plugin Feedback immédiat Zéro config end note } package "{name}-plugin/ (독립 빌드)" #CCE5FF { usecase "./gradlew 빌드" as BuildPlugin usecase "./gradlew publishToMavenLocal" as MavenLocal usecase "./gradlew test" as TestPlugin note bottom of BuildPlugin Cycle de vie isolé Tests unitaires + Cucumber CI dédiée possible end note } Clone -down-> Tasks Tasks -down-> Dogfood Dogfood ..> MavenLocal : "플러그인에 의존함\n로컬에서 게시됨" BuildPlugin -up-> MavenLocal TestPlugin -up-> BuildPlugin @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_구체적인_워크플로">구체적인 워크플로</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-shell hljs" data-lang="shell"># 1. Builder le plugin $ cd codebase-plugin $ ./gradlew publishToMavenLocal # 2. L'exercer depuis la racine $ cd .. $ ./gradlew indexCodebase queryCodebase snapshot # La boucle est fermée. Le plugin est testé dans des conditions # réelles de consommation, par le projet même qui l'héberge.</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_왜_이_아키텍처가_나를_사로잡았는가">왜 이 아키텍처가 나를 사로잡았는가?</h2> <div class="sectionbody"> <div class="paragraph"> <p>세 가지 혜택이 결합되면 «복제» 비용에 상응하는 가치가 있습니다 :</p> </div> <div class="sect2"> <h3 id="_1_네이티브_도그푸딩_즉각적인_피드백">1. 네이티브 도그푸딩, 즉각적인 피드백</h3> <div class="paragraph"> <p>Gradle 플러그인을 테스트하는 가장 좋은 방법은 사용하는 것이다. 모의 단위 테스트가 아닙니다. 아닌`GradleRunner`프로젝트와 함께 테스트. <strong>실제</strong> 빌드가 실제 파일에 플러그인을 적용합니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-shell hljs" data-lang="shell">$ git clone bakery-gradle $ cd bakery-gradle $ ./gradlew bake # ← le plugin est exercé immédiatement</code></pre> </div> </div> <div class="paragraph"> <p>플러그인이 깨진 경우, 루트 빌드가 이를 알려줍니다. 갈 필요가 없습니다. 외부 테스트 프로젝트를 찾는. 도그푸딩은 <strong>첫 번째</strong> 새로운 기여자가 시작하는 작업. 이것이 최종적인 smoke test입니다.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>규칙은 간단합니다 : 루트가 컴파일되고`./gradlew tasks` 플러그인 작업을 표시하고, 플러그인이 정상적으로 작동합니다. 놀라운 점은 없습니다. 생산 중</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_2_제로_콘피그_클로닝">2. 제로-콘피그 클로닝</h3> <div class="paragraph"> <p>Un `git clone && ./gradlew tasks`그리고 새로 온 사람은 모든 것을 본다 아무것도 설정하지 않고 걷다.`build.gradle.kts`뿌리는 플러그인의 살아있는 사용 설명서. Le`site.yml`옆에 예상된 구성을 보여줍니다.</p> </div> <div class="paragraph"> <p>대안과 비교해 보세요 : 세 개의 문단으로 구성된 README가 설명하십시오: 플러그인을 어떻게 빌드하고 프로젝트를 어떻게 빌드하는지 테스트의. 새로운 기여자가 README를 대각선으로 읽는다, 잘못하고, 이슈를 열어 — 그런데 정보가 <strong>실행 가능</strong> 해야 함</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>가장 견고한 문서는 읽는 문서가 아니다. 이것은 우리가<strong>실행하다</strong>. 루트 빌드는 문서입니다. 플러그인 실행 파일.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_3_격리된_빌드_독립된_ci">3. 격리된 빌드, 독립된 CI</h3> <div class="paragraph"> <p>플러그인에는 자체 Gradle 래퍼와 자체 수명 주기가 있습니다, 자신의 테스트. 할 수 있습니다 :</p> </div> <div class="ulist"> <ul> <li> <p>플러그인에서 루트를 건드리지 않고 Gradle 업그레이드</p> </li> <li> <p>플러그인에 종속성을 추가하지만 루트로 유출되지 않도록</p> </li> <li> <p>플러그인을 깨트리되 루트 빌드에 영향을 주지 않고 (당신이</p> </li> </ul> </div> <div class="paragraph"> <p>손상된 버전을 게시하지 마세요)</p> </div> <div class="ulist"> <ul> <li> <p>플러그인을 빌드/테스트하는 CI를 하나 가지고, 또 다른 CI는 플러그인을 실행하도록 하는</p> </li> </ul> </div> <div class="paragraph"> <p>root — 독립적으로</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">.github/workflows/ ├── test-plugin.yml → codebase-plugin/.gradlew build ├── test-root.yml → .gradlew tasks (vérifie que le plugin est consommable) └── publish.yml → codebase-plugin/.gradlew publish</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_서브_폴더의_해부학_name_plugin">서브 폴더의 해부학 `{name}-plugin/</h2> <div class="sectionbody"> <div class="paragraph"> <p>플러그인 폴더에 무엇이 있는지 좀 더 자세히 살펴봅시다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">codebase-plugin/ ├── gradlew ← wrapper indépendant ├── settings.gradle.kts ← @Suppress("UnstableApiUsage") │ + foobar-resolver-convention ├── build.gradle.kts ← java-gradle-plugin + signing + publish ├── gradle/ │ ├── libs.versions.toml ← catalogue complet (langchain4j, pgvector...) │ └── wrapper/ ├── buildSrc/ ← classes utilitaires buildSrc │ ├── build.gradle.kts │ └── src/main/kotlin/ │ ├── codebase/ ← CodebaseYmlAnonymizer, CodebaseConfiguration │ ├── benchmark/ ← BenchmarkConfig, BenchmarkProtocol │ ├── readme/ ← ReadmeYmlAnonymizer │ ├── site/ ← SiteYmlAnonymizer │ ├── slider/ ← SliderYmlAnonymizer │ └── snapshot/ ← SnapshotManager ├── src/ │ ├── main/kotlin/codebase/ │ │ ├── CodebasePlugin.kt ← class Plugin<Project> │ │ ├── rag/ ← pgvector, embedding, anonymization... │ │ ├── benchmark/ ← BenchmarkRunner, export, comparison... │ │ └── walker/ ← WorkspaceWalker │ └── test/ │ ├── kotlin/codebase/scenarios/ ← steps Cucumber │ ├── features/ ← .feature files │ └── resources/datasets/ ← fixtures .adoc, .yml, .json ├── .agents/ ← gouvernance agent (INDEX, SESSIONS, etc.) ├── AGENT.adoc ← règles agent ├── PROMPT_REPRISE.adoc ← mission session ├── BACKLOG.adoc ← backlog produit ├── snapshot.adoc ← snapshot auto-généré du projet └── embeds.yml ← config RAG embeds</code></pre> </div> </div> <div class="paragraph"> <p>거기에 다 있습니다. 루트와 하위 폴더 사이에 분산이 없습니다. 플러그인에서 작업하는 개발자한테 절대 필요하지 않다 떠나다`codebase-plugin/`. 플러그인을 사용하는 개발자 뿌리만 바라보고 — 그리고`build.gradle.kts`3줄의 그는 그에게 필요한 모든 것을 말해준다.</p> </div> <div class="sect2"> <h3 id="_버전_카탈로그_두_개의_별도_파일">버전 카탈로그 : 두 개의 별도 파일</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 37.5%;"> <col style="width: 37.5%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>gradle/libs.versions.toml</code>(뿌리)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{name}-plugin/gradle/libs.versions.toml</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">의존성 개수</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2-3 (플러그인 + README 선택 사항)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">30+ (langchain4j, pgvector, cucumber…​)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">역할</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">플러그인 소비</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">플러그인 빌드</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">누가 읽나</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">플러그인 사용자</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">플러그인 개발자</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>루트는 의도적으로 최소한의 카탈로그를 가지고 있다. 플러그인은 카탈로그를 가지고 있다. 완전. 혼동은 불가능합니다 : 각 빌드는 자신만의 스코프를 가집니다. 의존성의</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> <div class="paragraph"> <p>의존성 충돌을 디버깅하는 데 한 시간을 이미 보냈다면 당신의 플러그인과 테스트 프로젝트 사이에서, 그 가치를 이해합니다. 이 분리. 독립적인 카탈로그는 이 문제를 제거합니다. 구성으로.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_우리가_하지_않는_것">우리가 하지 않는 것</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 패턴은 마법이 아니다. 그것은 내가 지켜야 할 제약을 부과한다. 기꺼이 내게 가한다 :</p> </div> <div class="paragraph"> <p><strong>루트는 플러그인을 빌드하지 않습니다.</strong> 당신은 해야 합니다.<code>publishToMavenLocal</code> ou 루트가 이를 소비하기 전에 레포지터리에 배포하라.</p> </div> <div class="paragraph"> <p>이는 최소한의 비용이며, 이것이 <strong>좋은</strong> 제약입니다. 루트 플러그인을 외부 클라이언트처럼 소비합니다 — Maven을 통해. 정확히 서드파티 프로젝트가 하는 것처럼. 플러그인을 게시할 수 없는 경우, 루트가 즉시 알려줍니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-shell hljs" data-lang="shell"># La seule "friction" du pattern $ cd codebase-plugin && ./gradlew publishToMavenLocal && cd .. $ ./gradlew tasks --group=codebase</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_비교_세_가지_아키텍처가_마주하는_도그푸딩">비교 : 세 가지 아키텍처가 마주하는 도그푸딩</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 20%;"> <col style="width: 20%;"> <col style="width: 20%;"> <col style="width: 20%;"> <col style="width: 20%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">독립형 플러그인</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">모노레포`include()`</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">복합`includeBuild()`</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>루트 + 독립형 플러그인.</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">`git clone && gradlew tasks`플러그인의 작업을 제공한다</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(blank)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">루트와 독립적인 플러그인 빌드</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">카탈로그 버전 분리</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">없다`include()` ni <code>includeBuild()</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">네이티브 도그푸드 구성 없이</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">⚠️</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">독립형 CI 플러그인</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(Empty output)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Root은 실제 소비의 예시입니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">⚠️</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(No content to translate; output empty.)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>오른쪽 열은 모든 체크박스를 체크한다. 그러니깐 내가 더 뒤로 돌아가겠습니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_dag_계약_루트_빌드는_하위_폴더에서_절대_가져오지_않는다">DAG 계약: 루트 빌드는 하위 폴더에서 절대 가져오지 않는다.</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 아키텍처는 DAG N0→N3에 자연스럽게 통합됩니다. 내 워크스페이스에서. 패턴은 : *플러그인 N2는 허브입니다 그 자체의 종속성에서 N3 루트는 단말이다. 허브*를 적용하는</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 11 title DAG 계약 — 소비자 루트 vs 독립 플러그인 package "N3 — 뿌리 (저장소)" #FFCCCC { [build.gradle.kts (3 lignes)] as ROOT [libs.versions.toml (minimal)] as ROOT_TOML note right of ROOT plugins { bakery } bakery { configPath = ... } Aucune logique métier end note } package "N2 — {name}-plugin/" #CCFFCC { [build.gradle.kts (complet)] as PLUGIN [src/main/kotlin/] as SRC [gradle/libs.versions.toml] as PLUGIN_TOML [buildSrc/] as BUILDSRC note bottom of PLUGIN java-gradle-plugin signing + publish Tests unitaires + Cucumber CI dédiée end note } ROOT_TOML --> ROOT : "버전 플러그인" ROOT -down-> PLUGIN : "publishToMavenLocal" @enduml</pre> </div> </div> <div class="paragraph"> <p>Le <code>codebase-gradle/build.gradle.kts`6줄이다. 없다`src/</code>, 없음`buildSrc/<code>, 없어`gradle/rag-bench.gradle.kts</code>. 그냥 <code>plugins { alias(libs.plugins.codebase) }`그리고 저장소들. 모든 복잡함이 존재한다`codebase-plugin/</code>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_결론_시간을_절약해_주는_겉보기상의_중복">결론 : 시간을 절약해 주는 겉보기상의 중복</h2> <div class="sectionbody"> <div class="paragraph"> <p>내가 이 구조를 누군가에게 보여줄 때, 첫 번째 반응은 자주: “두 개 있어”<code>gradlew</code>, 두`settings.gradle.kts`, 두`libs.versions.toml`— 이건 중복입니다!</p> </div> <div class="paragraph"> <p>예. 그리고 아닙니다.</p> </div> <div class="paragraph"> <p>중복 »은 같은 정보를 두 곳에 복제하는 것이다. 여기서, 두 개의 <strong>별개의</strong> 파일은 두 가지 <strong>별개의</strong> 용도로 사용됩니다 : 플러그인 카탈로그 (30+ builder용 의존성)와 카탈로그 루트에서 (소비를 위해 2-3개의 의존성). 플러그인 래퍼 (개발을 위한 잠긴 버전)과 루트 래퍼 (잠시 다른 버전, 플러그인 연습을 위해).</p> </div> <div class="paragraph"> <p>이것은 <strong>분리의 책임</strong>이 빌드 시스템에 적용됩니다. 각 빌드 한 가지 일만 한다. 루트는 소비한다. 플러그인이 스스로 빌드된다.</p> </div> <div class="paragraph"> <p>비용? 한 주문`publishToMavenLocal`플러그인 빌드 사이 그리고 루트 빌드. 이점은? 아키텍처의 명확함을 제공하는 하류 디버깅에 소요되는 시간을 없앤다</p> </div> <div class="paragraph"> <p>이 패턴을 배포한 이후로`bakery-gradle`, <code>plantuml-gradle</code>, <code>codebase-gradle</code>, 그리고 다른 플러그인의`foundry/public/<code>, 저는 더 이상 주저하지 않고 내 저장소 중 하나에서 터미널을 열 때. 그 첫 번째 반사 —</code>./gradlew tasks`— 항상 걷고, 항상 준다 좋은 작업들, 그리고 모든 것이 정상인지 즉시 알려줍니다.</p> </div> <div class="paragraph"> <p>그게 바로 좋은 아키텍처다. README에서는 읽을 수 없다. 터미널에서 체험되며, 10초 미만에 이루어집니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_참고문헌">참고문헌</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>문서 0105 — Gradle 워크플로에 Graphify 통합하기</p> </li> <li> <p><a href="0117_granularisation_oss_css_repositorie_workspace_post.html">Article 0117 — OSS/CSS 세분화</a></p> </li> <li> <p><a href="0123_knowledge_graph_moteur_recommandation_articles_connexes_post.html">Article 0123 — Knowledge Graph을(를) 추천 엔진으로서</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0123_knowledge_graph_moteur_recommandation_articles_connexes_post.html Tue, 12 May 2026 00:00:00 +0000 blog/2026/0123_knowledge_graph_moteur_recommandation_articles_connexes_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_장면_화요일_5월_12일_오후_5시_30분">장면 : 화요일 5월 12일, 오후 5시 30분</a></li> <li><a href="#_진단_어떤_템플릿도_보지_못하는_세_가지_유형의_관계">진단 : 어떤 템플릿도 보지 못하는 세 가지 유형의 관계</a></li> <li><a href="#_해결책_gradle_파이프라인_뜨거운_llm_호출이_아님">해결책: Gradle 파이프라인, 뜨거운 LLM 호출이 아님</a> <ul class="sectlevel2"> <li><a href="#_아키텍처_베이커리가_그래피파이를_가져오고_엔진이_아님">아키텍처 : 베이커리가 그래피파이를 가져오고, 엔진이 아님</a></li> <li><a href="#_파이프라인_스캔_그래프_템플릿">파이프라인 : 스캔 → 그래프 → 템플릿</a></li> <li><a href="#_연대순의_폴백">연대순의 폴백</a></li> </ul> </li> <li><a href="#_신흥_온톨로지_기사들이_서로를_알지_못한_채_모일_때">신흥 온톨로지: 기사들이 서로를 알지 못한 채 모일 때</a></li> <li><a href="#_dag_계약_누가_누구에게_중요한가">DAG 계약: 누가 누구에게 중요한가</a></li> <li><a href="#_우리가_얻는_것_그리고_우리가_얻지_못하는_것">우리가 얻는 것 (그리고 우리가 얻지 못하는 것)</a></li> <li><a href="#_전망_블로그가_공개된_지식_그래프이다">전망: 블로그가 공개된 지식 그래프이다</a></li> <li><a href="#_결론_파일_시스템은_템플릿이_무시하는_것을_알고_있다">결론: 파일 시스템은 템플릿이 무시하는 것을 알고 있다.</a></li> <li><a href="#_참고문헌">참고문헌</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽기 시간 : 14 minutes</div> <p>pgvector와 LangChain4j 통합에 관한 기사를 읽고 계십니다. 페이지 하단에 JBake 연관 문서를 제안합니다. 클릭하면…​ 구성에 관한 문서입니다. Kitty Terminal의. 두 가지 사이의 유일한 공통점은? 그들은 미만으로 출판되었습니다. 15일 간격. 이것은 권고가 아닙니다. 이는 위장한 캘린더입니다. 사설.</p> </div> </div> </div> <div class="sect1"> <h2 id="_장면_화요일_5월_12일_오후_5시_30분">장면 : 화요일 5월 12일, 오후 5시 30분</h2> <div class="sectionbody"> <div class="paragraph"> <p>나는 내 기사 중 하나를 다시 읽고 있다 — <a href="0106_knowledge_graph_outil_comprehension_codebase_post.html">Knowledge Graph를 코드베이스 이해 도구로 하는 것에 관하여</a> 내용이 밀집되어 있습니다: 노드, 엣지, 커뮤니티, PlantUML, 온보딩. 한 기사 15분 읽기 기술은 참여를 유도한다`graphify-gradle`, <code>plantuml-gradle</code>, 그리고 그래프 토폴로지의 개념들</p> </div> <div class="paragraph"> <p>페이지 하단에, ‘관련 기사’가 나에게 제시한다:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Firebase Contact Form (0113)에 대한 기사</p> </li> <li> <p>Eager/Lazy 메커니즘에 관한 기사 (0108)</p> </li> <li> <p>Gradle 스크립트 → 플러그인 마이그레이션에 대한 기사 (0102)</p> </li> <li> <p>Ollama Pro 구독 누적에 관한 기사 (0120)</p> </li> </ol> </div> <div class="paragraph"> <p>이 네 개의 기사 중 세 개는 <strong>아무 관계도</strong> 지식 그래프와 관련이 없습니다. 그들이 거기에 있는 이유는 그들이 가장 최근에 게시되었기 때문입니다 — 시간적 근접성, 아니 의미론적 이웃</p> </div> <div class="paragraph"> <p>저는 템플릿을 보고 있어요.<code>post.thyme</code>[empty]</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xhtml hljs" data-lang="xhtml"><!-- Articles connexes (liens internes SEO) --> <th:block th:each="post,postStat : ${published_posts}"> <th:block th:if="${!post.uri.equals(content.uri) and postStat.index lt 4}"> ... </th:block> </th:block></code></pre> </div> </div> <div class="paragraph"> <p>`published_posts`연대순 목록입니다.`postStat.index lt 4`잡는다 현재 게시물이 아닌 처음 네 개. 그게 다야. 논리가 없습니다. 유사성. 내용에 대한 개념이 없다. 단지 루프일 뿐이다.`for`로 가장한 추천.</p> </div> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="⚠️"></i> </td> <td class="content"> <div class="paragraph"> <p>JBake의 버그가 아닙니다. 모든 것의 기본 동작입니다. 정적 사이트 생성기: 게시물 목록은 플랫하고 날짜순으로 정렬되어 있습니다. 템플릿은 가진 것을 가지고 가능한 한 최선을 다합니다.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>하지만 그렇다고 해서 그것을 받아들일 이유는 아니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_진단_어떤_템플릿도_보지_못하는_세_가지_유형의_관계">진단 : 어떤 템플릿도 보지 못하는 세 가지 유형의 관계</h2> <div class="sectionbody"> <div class="paragraph"> <p>내 기사 코퍼스 — 4개월 동안 23개의 게시물 — 풍부한 구조를 가진 시간순 템플릿이 완전히 압도한다 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>명시적 참조</strong> : 저는 사용합니다`xref:`내 기사에 대량으로</p> </li> </ol> </div> <div class="paragraph"> <p>문서 0122는 0106(knowledge graph)과 0116(compartimentage)를 참조합니다. (에피스테믹적). 이러한 링크들은 편집상의 <strong>hard linking</strong> 이다 — 나 의도적으로 이 개념들을 연결하기로 결정했습니다.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>공유된 태그</strong> : 각 기사는 몇 가지의`:jbake-tags:`. 기사에 대한</p> </li> </ol> </div> <div class="paragraph"> <p>Graphify + PlantUML (0105) 있다`gradle, graphify, plantuml, knowledge-graph`. Knowledge Graph (0106) 문서는 <code>knowledge-graph, graphify, plantuml</code>. 일곱 중 세 개의 태그가 일치합니다 — 43% 일치율.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>공동 발생하는 명명된 엔티티</strong> : « pgvector », « RAG », « embedding</p> </li> </ol> </div> <div class="paragraph"> <p>네 개의 다른 기사에 함께 나타납니다. « LangChain4j », Ollama", "플러그인 Gradle"는 여섯 다른 곳에 있습니다. 이것들은 태그가 아닙니다. 선언된 — 그것들은 코퍼스의 *patterns émergents*이며, 오직 한 NLP만 감지할 수 있다.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title 기사들 사이의 관계의 세 계층 package "층 1 — 명시적 참조" #CCFFCC { [Article A] as A1 [Article B] as B1 A1 -down-> B1 : xref: note right of A1 Liens durs Déterministes Déjà dans graph.json end note } package "레이어 2 — 공유된 태그" #FFFFCC { [Article A] as A2 [Article C] as C2 A2 ..> C2 : tag_cooccurrence note right of A2 Poids = tags communs / tags totaux Déterministes À extraire via graphify end note } package "3계층 — 발생적 온톨로지" #FFCCCC { [Corpus A] as A3 [Corpus B] as B3 A3 ..> B3 : entity_overlap note right of A3 Clusters NLP Co-occurrences d'entités nommées TF-IDF / cosine similarity end note } @enduml</pre> </div> </div> <div class="paragraph"> <p>오늘, 내 사이트는 이 세 레이어 중 <strong>아무것도</strong> 사용하지 않습니다. 그것은 사용 제로 레이어: Java 리스트의 삽입 순서.</p> </div> </div> </div> <div class="sect1"> <h2 id="_해결책_gradle_파이프라인_뜨거운_llm_호출이_아님">해결책: Gradle 파이프라인, 뜨거운 LLM 호출이 아님</h2> <div class="sectionbody"> <div class="paragraph"> <p>첫 번째 유혹은 bake 시점에 LLM을 호출하는 것일 것이다 : « Pour 이 문서에서 corpus에서 가장 유사한 세 개의 문서를 찾습니다. 그것을 하지 마세요.</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>각각에 대한 LLM 호출`./gradlew bake`시간과 돈이 들고, 그리고 비결정성을 빌드에 도입합니다. LLM의 응답은 두 빌드 사이에서 내용이 변경되지 않은 채 전환할 수 있습니다. 귀하의 CI가 됩니다. 재현할 수 없습니다, 여러분의 테스트는 불안정해집니다.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>해결책은 결정적입니다: 그래프를 사전 계산하는 Gradle 파이프라인 유사성과 그것을 안에 저장합니다`graph.json`. 템플릿이 결과를 읽는다 그는 절대로 계산을 시작하지 않는다.</p> </div> <div class="sect2"> <h3 id="_아키텍처_베이커리가_그래피파이를_가져오고_엔진이_아님">아키텍처 : 베이커리가 그래피파이를 가져오고, 엔진이 아님</h3> <div class="paragraph"> <p>이것은 건축 설계에서 가장 중요한 점입니다. 유혹이 될 것이다 협업을 연결하여 안에`engine/build.gradle.kts`: 엔진이 적용됩니다 graphify는 스캔을 위해, bakery는 베이크를 위해, engine은 사이에 다리를 놓는다 둘 다</p> </div> <div class="paragraph"> <p>이것은 안티패턴입니다. Engine은 *소비자 터미널*입니다 — 적용합니다 플러그인이지만 비즈니스 로직을 구현하지 않습니다. 규칙은 : <strong>증명 책임은 독점 플러그인에 있다.</strong></p> </div> <div class="listingblock"> <div class="title">올바른 아키텍처 — Bakery가 Graphify를 가져옵니다</div> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam packageBackgroundColor #FFF3CD title 베이커리가 Graphify를 가져옵니다 — 엔진은 아무것도 모릅니다. package "N3 — 엔진" #FFCCCC { [engine/build.gradle.kts] as ENG note right of ENG plugins { bakery } Zéro connaissance de graphify 4 tâches, ~150 lignes end note } package "N2 — 빵집" #CCFFCC { [bakery-plugin] as BAK note right of BAK plugins { graphify } ← import interne Lit graph.json Résout articles connexes Expose le modèle à JBake end note } package "N0 — 그래파이" #CCE5FF { [graphify-plugin] as GRF note right of GRF Scan workspace → graph.json Enrichi avec : - xref: edges - co-occurrences de tags - entités nommées (NLP) end note } ENG -down-> BAK : "플러그인 { 빵집 }" BAK -down-> GRF : "플러그인 { graphify } ← N2→N0 확인" @enduml</pre> </div> </div> <div class="paragraph"> <p>DAG 계약이 준수됩니다: bakery (N2)는 graphify (N0)를 임포트합니다, N2 > N0, 위반 없음. Engine (N3)는 bakery (N2)를 가져옵니다. N3 > N2, 정상.</p> </div> <div class="paragraph"> <p>엔진에는 참조하는 코드 줄이 *aucune*개 없습니다.<code>graph.json</code>, <code>relatedPosts</code>, 또는 다른 모든 유사성 개념. 그는 베이커리를 적용한다, 마침표. 라 협력은 베이커리 내부적이다</p> </div> </div> <div class="sect2"> <h3 id="_파이프라인_스캔_그래프_템플릿">파이프라인 : 스캔 → 그래프 → 템플릿</h3> <div class="paragraph"> <p>다음은 세 단계로 구성된 전체 파이프라인입니다 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>스캔</strong> (그래프화) :`graphify-plugin`워크스페이스를 스캔합니다. 그의</p> </li> </ol> </div> <div class="paragraph"> <p>현재 형태로는 이미 그것들을 감지합니다`xref:`사이`.adoc`그리고 에 노출하다`graph.json`유형 테두리처럼`reference`.<br> 편집 콘텐츠를 위해 이를 풍부하게 합니다: * JBake 메타데이터를 파싱 (<code>:jbake-tags:</code>, <code>:jbake-description:</code>) 각의`.adoc`블로그의 * 태그 공출현 계산 → 간선`tag_cooccurrence`무게와 함께 * TF-IDF를 통해 설명에서 명명된 엔티티 추출 → edges`entity_overlap` * 섹션을 삽입합니다`blog_articles`안에`graph.json`존재하는<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// Extrait de l'enrichissement graphify pour le blog fun enrichBlogSection(graphJson: File, blogDir: File): GraphJson { val articles = blogDir.listFiles { f -> f.extension == "adoc" } .map { parseJbakeMetadata(it) } val nodes = articles.map { ArticleNode(it.slug, it.title, it.tags) } val edges = mutableListOf<GraphEdge>() // Couche 1 : xref (déjà fait par scanWorkspace) // Couche 2 : co-occurrences de tags for (a in articles) { for (b in articles) { if (a.slug == b.slug) continue val common = a.tags.intersect(b.tags) if (common.isNotEmpty()) { edges.add(GraphEdge( source = a.slug, target = b.slug, type = "tag_cooccurrence", weight = common.size.toDouble() / (a.tags.size + b.tags.size) )) } } } return graphJson.copy( blogArticles = BlogSection(nodes, edges) ) }</code></pre> </div> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Bake</strong> (베이커리) : 순간의`./gradlew bake`, `BakeryPlugin`침대</p> </li> </ol> </div> <div class="paragraph"> <p>`graph.json`관련 글을 각 포스트에 대해 해결합니다.<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// BakeryPlugin — résolution des articles connexes fun resolveRelatedPosts( currentSlug: String, graph: GraphJson, maxResults: Int = 4 ): List<RelatedPost> { val edges = graph.blogArticles.edges .filter { it.source == currentSlug || it.target == currentSlug } return edges .sortedByDescending { it.weight } .take(maxResults) .map { edge -> val relatedSlug = if (edge.source == currentSlug) edge.target else edge.source graph.blogArticles.nodes.first { it.slug == relatedSlug } } }</code></pre> </div> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Template</strong> (<code>post.thyme</code>) : JBake 모델은 이제 맵을 받습니다</p> </li> </ol> </div> <div class="paragraph"> <p>플랫한 연대순 목록 대신 구조화된 형태<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xhtml hljs" data-lang="xhtml"><!-- Articles connexes basés sur le Knowledge Graph --> <th:block th:if="${relatedPosts != null and !relatedPosts.empty}"> <section class="mt-5 pt-4 border-top"> <h2 class="h4 mb-3">Articles connexes</h2> <th:block th:each="related : ${relatedPosts}"> <div class="mb-2"> <a th:href="${content.rootpath} + ${related.uri}" th:text="${related.title}" class="fw-semibold"></a> <br/> <small class="text-muted"> <th:block th:each="reason,iterStat : ${related.reasons}"> <span class="badge bg-light text-dark" th:text="${reason}"></span> </th:block> </small> </div> </th:block> </section> </th:block></code></pre> </div> </div> <div class="paragraph"> <p>템플릿은 동일합니다 — 데이터가 <strong>어디서</strong> 오는지 모릅니다. 베이커리와 JBake 사이의 계약만 변경되었습니다 :`published_posts`(목록) 순차적인) 된다`relatedPosts`(그래프 가중 맵).</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> <div class="paragraph"> <p>배지 « 이유 » (예:`xref 0122`, <code>tag:gradle</code>, <code>cluster:pgvector-rag</code>) 설명해 줍니다: 독자에게 <strong>왜</strong> 이 기사가 관련되는지. 이것은 아니다 투명성만으로는 — 토폴로지에 대한 교육이야 당신의 내용. (Empty)</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_연대순의_폴백">연대순의 폴백</h3> <div class="paragraph"> <p>Si `graph.json`없습니다 (로컬 빌드, 사전 스캔 없이, 첫 배포, 아직 graphify 스캔을 통합하지 않은 CI), 템플릿 우아하게 저하되어야 합니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">fun resolveRelatedPosts(currentSlug: String, graph: GraphJson?): List<RelatedPost> { if (graph != null && graph.blogArticles != null) { return resolveFromGraph(currentSlug, graph) } // Fallback chronologique — même comportement qu'aujourd'hui logger.warn("[bakery] graph.json absent — fallback chronologique") return resolveFromChronology(currentSlug) }</code></pre> </div> </div> <div class="paragraph"> <p>기본 동작은 현재 동작과 동일합니다. Le 추천 엔진은 <strong>점진적인 개선</strong> — 아닙니다 파괴적인 변경.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_신흥_온톨로지_기사들이_서로를_알지_못한_채_모일_때">신흥 온톨로지: 기사들이 서로를 알지 못한 채 모일 때</h2> <div class="sectionbody"> <div class="paragraph"> <p>가장 흥미로운 층은 세 번째 층: 신흥 온톨로지. 인용되지 않은 글, 태그가 같은 것이 아닌 글, 하지만 서로 <strong>같은 것에 대해 말하는</strong> 사람들도 모르게.</p> </div> <div class="paragraph"> <p>구체적인 예를 들어 봅시다. 내 코퍼스에 있는 세 개의 기사:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>0119 — 벤치마크 DGX Spark vs Cloud LLM 구독</p> </li> <li> <p>0121 — Gradle 플러그인 Ollama Pro 두 인스턴스 제어</p> </li> <li> <p>0122 — 효율 비율 27x 45x 함대 AI 전문가</p> </li> </ol> </div> <div class="paragraph"> <p>이 세 개의 기사 사이에는 xref가 <strong>아무것도</strong> 없습니다. 그들의 태그는 하지 않다 20% (« ollama », « llm » 일반적)으로만 일치합니다. 그러나 가벼운 NLP 설명에 대해 명백한 클러스터가 드러납니다 : « 비용 », « 구독 », 클라우드 », « GPU », « API 키 », « Ollama Pro », « 효율성 », « 비율</p> </div> <div class="paragraph"> <p>그들은 온톨로지 클러스터를 형성합니다 : <strong>LLM 자체 호스팅의 경제 vs cloud</strong>. 이 클러스터는 어디에서도 선언되지 않았습니다. 이것은 코퍼스에서 발생합니다.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam packageBackgroundColor #E8F8F5 title Cluster Ontologique Émergent — "경제적 LLM Self-Hosted" package "감지된 클러스터: 경제-llm" #D5F5E3 { [0119 — Benchmark DGX Spark\nvs Cloud Abonnement] as A [0121 — Plugin Gradle Piloter\nDeux Instances Ollama Pro] as B [0122 — Ratio Efficacité\n27x 45x Flotte Experts] as C } A .. B : entity_overlap (0.73) B .. C : entity_overlap (0.81) A .. C : entity_overlap (0.68) note bottom of A Aucun xref entre ces articles. Tags communs : "ollama", "대규모 언어 모델". Cluster découvert par NLP : co-occurrences "비용", "GPU", "구독", "Ollama Pro". end note @enduml</pre> </div> </div> <div class="paragraph"> <p>이 온톨로지 클러스터는 복합 엣지가 된다`graph.json`[No output - empty string]</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{ "source": "0119-benchmark-dgx-spark", "target": "cluster:economie-llm", "type": "entity_cluster", "weight": 0.73, "metadata": { "clusterLabel": "Économie LLM Self-Hosted vs Cloud", "commonEntities": ["coût", "GPU", "abonnement", "Ollama Pro", "ratio"], "articlesInCluster": [ "0119-benchmark-dgx-spark", "0121-ollama-pro-deux-instances", "0122-ratio-efficacite-flotte-experts" ] } }</code></pre> </div> </div> <div class="paragraph"> <p>NLP는 의도적으로 가볍습니다 — TF-IDF + 코사인 유사성 (대상에 대한) 설명. BERT가 필요하지 않습니다, 언어 모델이 필요하지 않습니다. 코퍼스는 23개의 문서로 구성되어 있으며, 유사도 행렬은 한 50 Ko 크기의 JSON 파일.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>NLP의 힘은 알고리즘의 정교함에서 비롯되지 않습니다, 하지만 *코퍼스 크기*와 *설명 품질>. 한 `:jbake-description:`bien 쓰여진 150자에는 더 많은 TF-IDF에 대한 신호: 3000단어 전체 기사</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_dag_계약_누가_누구에게_중요한가">DAG 계약: 누가 누구에게 중요한가</h2> <div class="sectionbody"> <div class="paragraph"> <p>이것이 건축 학문이 보상을 받는 지점이다. 이 DAG N0→N3 정의된`engine/build.gradle.kts`간단한 규칙을 제시한다 : 어떤 프로젝트도 상위 수준의 프로젝트를 임포트하지 않습니다.</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 27.2728%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">소비자 플러그인</th> <th class="tableblock halign-left valign-top">가져온 플러그인</th> <th class="tableblock halign-left valign-top">소비자 수준</th> <th class="tableblock halign-left valign-top">가져온 레벨</th> <th class="tableblock halign-left valign-top">유효합니까 ?</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">베이커리-그레이들</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">graphify-gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ N2 > N0 — OK</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">엔진</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">베이커리-그레이들</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ N3 > N2 — OK</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">엔진</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">graphify-gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ 기술 OK, 그러나 <strong>개념적으로 틀림</strong> — 협력은 빵집 내부에서 이루어진다.</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Engine 적용하다 bakery. Bakery 적용하다 graphify. 이건데 다. manifests 언젠가 저는 연구를 위해 벡터 스토어 코드베이스 (N1)를 추가하고 싶어요. 의미 교차 코퍼스, 베이커리도これを인포트합니다. 엔진은 변하지 않습니다.</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>패턴은 : <strong>N2 플러그인은 자체 의존성의 허브입니다</strong> Engine N3은 허브가 아니라 허브를 적용하는 터미널이다.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_우리가_얻는_것_그리고_우리가_얻지_못하는_것">우리가 얻는 것 (그리고 우리가 얻지 못하는 것)</h2> <div class="sectionbody"> <div class="paragraph"> <p>주요 이점은 편집적인 것이지 기술적인 것이 아닙니다</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">이전</th> <th class="tableblock halign-left valign-top">이후</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">관련 기사 = 4 최신 글</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">관련 글 = Knowledge Graph에서 가중치 상위 4개</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">리더가 RAG를 읽음 → Kitty Terminal 추천</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">독자가 RAG를 읽는다 → 추천 pgvector, chunking, vector store</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">왜에 대한 투명함이 전혀 없습니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">뱃지`xref 0122`, <code>tag:gradle</code>, `cluster:rag`보이는</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">JBake 표준, 노력 제로, 가치 제로</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">결정적, 재현 가능, 테스트 가능한 Gradle 파이프라인</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">읽는 사람에게 학습 곡선이 없습니다</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">독자는 내 내용의 *topologie*를 발견한다.</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>우리가 얻지 못하는 것 :</p> </div> <div class="ulist"> <ul> <li> <p>이것은 "참된" 추천 엔진이 아닙니다 (협업 기반이 아닌</p> </li> </ul> </div> <div class="paragraph"> <p>필터링, A/B 테스트 없음, 피드백 루프 없음)</p> </div> <div class="ulist"> <ul> <li> <p>품질은 JBake 메타데이터의 풍부함에 달려 있다 — 만약 당신의</p> </li> </ul> </div> <div class="paragraph"> <p>설명이 비어 있습니다, TF-IDF는 아무것도 보지 못합니다</p> </div> <div class="ulist"> <ul> <li> <p>NLP는 오프라인 상태이며 — 새 기사들은 여기서만 클러스터화됩니다</p> </li> </ul> </div> <div class="paragraph"> <p>다음 스캔 (좋아요 : 빌드는 여전히 결정적입니다)</p> </div> </div> </div> <div class="sect1"> <h2 id="_전망_블로그가_공개된_지식_그래프이다">전망: 블로그가 공개된 지식 그래프이다</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 기능은 더 넓은 관점을 열어줍니다: 그리고 만약`cheroliv.com` 그 자신 *knowledge graph navigable*가 되고 있었는가?</p> </div> <div class="paragraph"> <p>기사는 노드입니다. 태그는 커뮤니티입니다. xref는 간선들. 독자는 더 이상 고립된 기사를 읽지 않는다 — 그는 에서 탐색한다 *지식 그래프*에서 현재 문서는 진입점입니다.</p> </div> <div class="paragraph"> <p>시간순 목록이 아닌 홈페이지를 상상해 보세요. 최근 게시물, 하지만 <strong>corpus 지도</strong> : 온톨로지 클러스터, 피벗 항목 (가장 가장자리가 많은), 읽기 경로 추천 (« Graphify에 대한 글을 좋아하셨다면, 다음을 읽어보세요 Knowledge Graph를 이해 도구로 삼는 것</p> </div> <div class="paragraph"> <p>이제 블로그가 아닙니다. 이것은 *시맨틱 아틀라스*입니다.</p> </div> <div class="paragraph"> <p>그리고 이것은 과학 소설이 아닙니다.`graph.json`이미 존재한다 그에게는 탐색 인터페이스만 부족합니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_결론_파일_시스템은_템플릿이_무시하는_것을_알고_있다">결론: 파일 시스템은 템플릿이 무시하는 것을 알고 있다.</h2> <div class="sectionbody"> <div class="paragraph"> <p>내가 화요일 저녁에 설계한 건 한 가지 휴리스틱의 대체다. 게으른 (연대순) 에 의한 정확한 표현의 내 코퍼스(지식 그래프)의 구조.</p> </div> <div class="paragraph"> <p>템플릿`post.thyme`변하지 않는다. 바뀌는 것은 우리가 하는 것이다. 그에게 먹이를 준다. 전 : 정렬된 Java 목록`date`. 후 : 세 층 분석에서 유도된 가중 그래프 — xrefs, 동시 발생 태그와, 그리고 NLP에 의한 신흥 온톨로지.</p> </div> <div class="paragraph"> <p>루프가 닫혔습니다. graphify가 워크스페이스를 스캔합니다. Bakery가 읽습니다 그래프가 템플릿을 먹입니다. 독자는 추천을 봅니다 관련된. 그리고 엔진 — 지휘자 — 는조차도 모르는 그 모든 것이 있다.</p> </div> <div class="paragraph"> <p>이게 바로 좋은 아키텍처입니다. 각 플러그인은 한 가지 일을 합니다. 그리고 소비자 단말은 어떻게 해야 하는지 알 필요가 없습니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_참고문헌">참고문헌</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>문서 0105 — Graphify를 Gradle 워크플로에 통합</p> </li> <li> <p><a href="0106_knowledge_graph_outil_comprehension_codebase_post.html">Article 0106 — 지식 그래프를 이해 도구로</a></p> </li> <li> <p><a href="0117_granularisation_oss_css_repositorie_workspace_post.html">Article 0117 — La Granularisation OSS/CSS</a></p> </li> <li> <p><a href="0121_plugin_gradle_piloter_deux_instances_ollama_pro_post.html">Article 0121 — Gradle 플러그인 Ollama Pro 두 인스턴스 제어</a></p> </li> <li> <p>문서 0122 — 27배에서 45배 더 효율적 : AI 전문가 함대</p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0122_ratio_efficacite_27x_45x_flotte_experts_ia_vs_claude_gpt_post.html Mon, 11 May 2026 00:00:00 +0000 blog/2026/0122_ratio_efficacite_27x_45x_flotte_experts_ia_vs_claude_gpt_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_문제_왜_파인튜닝을_하고_rag를_하지_않는가">문제: 왜 파인튜닝을 하고 RAG를 하지 않는가?</a></li> <li><a href="#_아이디어_전문가들의_함대_단일_모델이_아니다">아이디어: 전문가들의 함대, 단일 모델이 아니다.</a></li> <li><a href="#_현미경_아래_코드베이스_7_900_파일_144_000_줄">현미경 아래 코드베이스: 7 900 파일, 144 000 줄</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽는 시간 : 22 minutes</div> <p>일상적인 소프트웨어 개발에서 LLM을 사용할 때, 결국 항상 같은 벽에 부딪히게 됩니다: 모델은 <strong>당신의</strong> 코드베이스를 알지 못합니다. 당신이 그런 패턴의를 사용하고 있다는 것을 알지 못합니다.https://fr.wikipedia.org/wiki/Graphe_orient%C3%A9_acyclique[DAG], 그런 Gradle 관례, 그런 인식론적 계층화 당신의https://fr.wikipedia.org/wiki/AsciiDoc[.adoc]. 그러면 그에게 맥락을 주입하고, 반복하고, 수정하고, 반복한다. 그리고 시간과 돈이 흐른다.</p> </div> <div class="paragraph"> <p>그래서 나는 직설적으로 질문을 던졌다: 내 워크스페이스에서 fine-tuned된 모델 팀이 내 스타일로 코드를 뱉어내며 매번 설명할 필요 없이 작동하는 데 드는 비용은 얼마나 될까? 그리고 무엇보다: 이 접근 방식이 기존의 전용 솔루션인 Claude, GPT, Gemini, Grok과 어떻게 비교되는가?</p> </div> <div class="paragraph"> <p>그 대답이 저를 놀라게 했어요. 내가 생각한 것보다 훨씬 적었어요. 그리고 해당 업계 거인들에 대한 비용 대비 효율성 비율은 비열합니다. 자세한 내용은 다음과 같습니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_문제_왜_파인튜닝을_하고_rag를_하지_않는가">문제: 왜 파인튜닝을 하고 RAG를 하지 않는가?</h2> <div class="sectionbody"> <div class="paragraph"> <p>RAG는 괜찮습니다. <a href="0106_knowledge_graph_outil_comprehension_codebase_post.html">Mon knowledge graph</a> 및 <a href="0116_compartimentage_epistemique_automatise_llm_post.html">mon compartimentage épistémique</a>가 작동합니다. 하지만 RAG에는 근본적인 결함이 있습니다: 매 쿼리마다 관련 컨텍스트를 다시 주입해야 합니다. 프롬프트가 길어지고, 지연이 급증하며, 모델은 절대 당신의 패턴을 내면화하지 않습니다 — 매번 외부 문서처럼 읽습니다.</p> </div> <div class="paragraph"> <p>파인튜닝은 근육 기억입니다. 모델은 <strong>알고</strong> 있습니다 당신이 쓰고 있다는 것입니다.<code>build.gradle.kts`통해 기록된 작업을 가진`tasks.register</code>, 당신의`AGENTS.adoc`표준화된 구문이 뒤따르고, 당신의 워크스페이스가 버러로 구조화되어 있다는 것을. 그는 상기시킬 필요가 없습니다.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> <div class="paragraph"> <p>파인튜닝은 RAG의 대체가 아닙니다. 이는 보완적인 계층입니다. RAG는 자주 변경되는 데이터(로그, 티켓, 최신 커밋 등)에 여전히 관련이 있습니다. 파인튜닝은 장기적인 <strong>구조적</strong> 및 <strong>스타일리틱</strong> 지식을 위해 사용됩니다.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_아이디어_전문가들의_함대_단일_모델이_아니다">아이디어: 전문가들의 함대, 단일 모델이 아니다.</h2> <div class="sectionbody"> <div class="paragraph"> <p>내 작업 공간 전체에 하나만 파인튜닝된 모델을 사용해도 충분하다. 하지만 이는 최적이 아니다. 내 작업 공간은 매우 다양한 분야를 포괄한다:</p> </div> <div class="ulist"> <ul> <li> <p>Gradle 플러그인 (Kotlin, 컨벤션 플러그인, 복합 빌드)</p> </li> <li> <p>DAG 엔진 (Kotlin, 계획, 실행)</p> </li> <li> <p>LLM 에이전트 (Python, LangChain4j, RAG)</p> </li> <li> <p>아키텍처 문서 (AsciiDoc, 거버넌스)</p> </li> <li> <p>인프라/데브옵스 (Docker, GitHub Actions, CI/CD)</p> </li> </ul> </div> <div class="paragraph"> <p>하나의 모델은 어디서든 좋지만, 어디에서도 뛰어나지 않아야 한다. 해결책? 하나<strong>특수 모델 함대</strong>, 각 요청을 적절한 전문가로 라우팅하는 오케스트레이터가 있다.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FAFAFA skinparam defaultFontSize 13 package "Ollama 클라우드" { rectangle "DeepSeek V4-Pro 1.6T / 49B 자산" as V4Pro #FF6B6B rectangle "6× V4-Flash-FT 292B / 13B 활성" as Flash #4ECDC4 rectangle "6× Gemma4 26B-FT\n26B / 3.8B 활성" as Gemma #FFE66D rectangle "5× Qwen3.6 35B-FT 35B / 3B 활성" as Qwen36 #A8E6CF rectangle "5× Qwen3.5 35B-FT 35B / 3B 활성" as Qwen35 #FF8B94 } note bottom of Qwen35 À partir de 17€/mois (1× Ollama Pro annual) Extensible par cumul de comptes Pro selon la méthode Docker. end note actor Utilisateur as User User --> V4Pro : Requête V4Pro --> Flash : "복잡한 Gradle 작업" V4Pro --> Gemma : "아스키독 포맷" V4Pro --> Qwen36 : "코틀린 리팩터링" V4Pro --> Qwen35 : "Bash 스크립트" note right of V4Pro L'orkestrateur route la requête vers l'expert le plus pertinent. Zéro prompt engineering répétitif. end note @enduml</pre> </div> </div> <div class="paragraph"> <p>전체 함대 :<strong>1 오케스트레이터 + 22 전문가 = 23 모델</strong>. 그리고 월간 추론 비용은 얼마인가요?<strong>17€/월</strong>연간 Ollama Pro 구독 — 할당량이 초과되면 계정을 누적하여 확장 가능하며, 이는 <a href="0120_cumuler_deux_abonnements_ollama_pro_docker_post.html">다중 계정 Docker 방법</a>에서 보여준 바와 같이입니다. 17유로에서 시작하여 실제 필요에 따라 단계별로 20유로를 추가합니다. 낭비 없음.</p> </div> </div> </div> <div class="sect1"> <h2 id="_현미경_아래_코드베이스_7_900_파일_144_000_줄">현미경 아래 코드베이스: 7 900 파일, 144 000 줄</h2> <div class="sectionbody"> <div class="paragraph"> <p>훈련 비용을 추정하기 전에, 어떤 것을 훈련해야 하는지 알아야 합니다. Git이 무시하는 모든 것을 철저히 제외하고 내 워크스페이스를 감사했습니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- ---- build/ out/ node_modules/ runtimes/ .gradle/ dist/ target/ venv/ __pycache__/ .cache/ .tox/ ---- 추적된 파일에 대한 결과는 다음과 같습니다 : [cols="2,2"] |=== |미터법 |가치 |추적된 소스 파일 |**7,896** |코드 라인 (LOC) |**143 805** |Git 저장소 |**26** |주요 언어 |Kotlin (1 903), AsciiDoc (2 765), Python (5 029) |=== [IMPORTANT] ==== 이 5,000+ 파이썬 파일들은 포함됩니다`runtimes/`노트북과 유틸리티 스크립트. 애플리케이션 핵심(Gradle 플러그인, DAG 엔진, 에이전트)은 주로 Kotlin과 AsciiDoc으로 작성되었습니다. ==== 이 질량을 기준으로, 의 합성 데이터셋을 생성할 수 있다고 추정합니다**~1억 7천만 토큰**인스트럭터 LLM을 통해 (코드베이스를 instruction/response 쌍으로 증류). === 전문가 유형별 데이터 세트 세부 사항 [source,text] ---- Dataset maître (généraliste V4-Flash) : 50M tokens Expert Gradle/Build : 15M tokens Expert Kotlin/DAG : 15M tokens Expert AsciiDoc/Gouvernance: 15M tokens Expert Agent/LLM/Python : 15M tokens Expert Infra/CI-CD : 15M tokens Micro-experts Qwen/Gemma : ~5M tokens chacun ---- == 모델 선택: 100% MoE, 밀도 제로 여기가 건축이 진정으로 효율적으로 변하는 곳이다. *밀집* 모델은 모든 토큰에 대해 모든 가중치를 활성화합니다. *MoE* (Mixture of Experts) 모델은 매개변수의 일부만 활성화합니다. 추론 비용 — 그리고 파인튜닝 비용 — 은 매개변수에 비례합니다.**활성화된**, 파라미터에 적용되지 않음**저장된**. 올라마 클라우드에서 오늘 시장에서 MoE가 제공하는 것을 살펴봅시다 : [cols="3,2,2,1,3"] |=== |모델 |총 파라미터 |활성화된 |활성화 |올라마 클라우드 |DeepSeek V4-Pro |1.6T |49B |3.1% |✅ 토착의 |DeepSeek V4-Flash |292B |13B |4.5% |✅ 토착의 |Gemma 4 26B-A4B |26B |3.8B |14.6% |✅ 토착의 |Qwen3.6-35B-A3B |35B |3B |8.6% |❌ (아직 통합되지 않음) |Qwen3.5-35B-A3B |35B |3B |8.6% |✅ 토착의 |❌ Qwen3.5-27B |27B |27B |100% 밀집된 |제거된 |❌ Qwen3.5-4B/9B |4B/9B |4B/9B |100% 조밀한 |제외된 |❌ Gemma 4 31B |31B |31B |100%밀집된 |제거된 |🧪 Gemma 4 E2B/E4B |5B/8B |5B/8B |100% 밀도 |검증 파이프라인 |=== [CAUTION] ==== 활성화 비율은 판별 기준이다. Gemma 4 26B-A4B는 전체 26B 매개변수 중 3.8B만 활성화한다 — 이는 밀집형 27B에 비해 7배 적으며, 코딩 에이전트 성능은 비슷하다(LiveCodeBench v6에서 77.1% 대 80%). ==== === 왜 나는 밀집 모델들을 포기하는가? 예외: Gemma 4 E2B와 E4B 모델. 이 두 모델은 Apache 2.0 라이선스 하에 있으며, 비용을 최소화하여 학습 파이프라인을 테스트하고 검증하기에 적합합니다. E2B에서 2-3시간 실행 비용은 $5 미만 — 데이터셋이나 하이퍼파라미터가 문제가 있다면 몇 달러만으로도 알 수 있습니다. 파이프라인이 안정되면 심지어 초미세 작업(트리ivial 재포맷팅, 이진 분류)에도 사용할 수 있습니다. 그러나 주력 함대의 전문가들에 대해서는 저는 여전히 MoE를 선호합니다. 그 이유는: .しかしだけではない: これらのGemma 4 E2B/E4B, 細かい匿名化の専門家 [NOTE] ==== Google은 이러한 작은 모델들을 네이티브 툴 호출에서 경쟁력 있게 설계했습니다 — 그들은 함수를 호출하고, 정규 표현식을 조작하며, 패턴을 검색할 수 있습니다. 익명화 예시(이메일, 토큰, UUID, 파일 경로)로 파인튜닝한 후, 그들은**데이터셋 익명화 도구**초고속. 그들에게 원시 텍스트 블록을 주면, 그들은 이를 호출한다.`sed`/`regex`툴 호출을 통해 정리된 블록을 반환합니다. 추론 비용은 미미합니다: 5B가 활성화되어 보급형 GPU 한 장이면 충분합니다. 이 모델들은 비즈니스 전문가가 아닙니다 — 이들은**숙련된 노동자**데이터셋의 생산 체인에서 ==== * 그 훈련 VRAM(QLoRA에서도 마찬가지)는 다음과에 비례한다**총 27B** * 그의 훈련 시간은 비례한다**27B 활성화된** Qwen3.6-35B-A3B (MoE)와 비교해 봅시다: [cols="3,2,2,2"] |=== | |Qwen3.5-27B (밀집) |Qwen3.6-35B-A3B (MoE) |비율 |VRAM QLoRA |~55 GB |~35 GB |1.6× |GPU 시간 (8M 토크) |~12시간 |~4시간 |**3배** |파인 튜닝당 비용 |~$24 |~$8 |**3×** |SWE-bench 검증됨 |75.0% |73.4% |비교 가능한 |=== MoE는 에이전트 코딩 성능을 5% 차이로 훈련하는 데 3배 더 저렴합니다. 22명의 전문가 사이에서 차이가 수천 유로에 달합니다. == 트레이닝 추정 : 811 H100-시간 나는 위에서 설명한 데이터셋을 기반으로 QLoRA 4-bit을 이용해 모델별 훈련 비용을 세분화했다. === 경량 마이크로 전문가 MoE (3-3.8B 활성화된) 이 모델은 실행당 H100 1개(80 GB)가 필요합니다. 모델의 Q4 VRAM은 대략 13-18 GB이며, LoRA 옵티마이저 상태와 활성화에 충분한 공간을 남깁니다. [cols="4,2,3,2"] |=== |모델 |실행 횟수 |GPU-시간/실행 |총 GPU-h |Gemma 4 26B-A4B-FT |6 |3.5 h |**21시** |Qwen3.6-35B-A3B-FT |5 |4.0 h |**20시** |Qwen3.5-35B-A3B-FT |5 |4.0 h |**20시간** |소계 마이크로 | | |*61 h* |=== === 임원용 V4-Flash (13B 활성화 / 292B 저장) DeepSeek V4-Flash는 특별한 경우이다. 토큰당 13B만 활성화되더라도 Q4의 전체 모델은 약 142 GB로 — 훈련 중에 모든 전문가들이 VRAM에 있어야 합니다. 따라서**3× H100**달리면서 편안해지기 위해 [cols="4,2,3,3,2"] |=== |모델 |데이터셋 |그래픽 처리 장치 |시간 |총 GPU-시간 |V4-Flash-Base 범용 |50M 토큰 |3배 H100 |50 h |**150시간** |V4-Flash 전문가 ×5 |15M 토큰 |3배 H100 |40 h |**600시간** |임원 소계 | | | |*750 h* |=== [cols="3,2,1"] |=== |**합계** | |**811 H100-h** |=== [NOTE] ==== 비교를 위해, QLoRA 없이 V4-Flash의 전체 파인튜닝은 약 4000 H100시간이 6개 모델에만 소요됩니다. QLoRA는 비용을 5로 나눕니다. 이는 이 규모에서 프로젝트를 경제적으로 실행 가능하게 만드는 유일한 방법입니다. ==== === GPU 가격 : 2026년 5월에 누가 무엇을 대여하고 있나요? 저는 주요 H100 대여 업체를 벤치마크했습니다. 계량 요금은 811시간 기준입니다. [cols="3,2,2,2"] |=== |임대인 |$/H100·h |총 811h |신뢰성 |**Vast.ai 스팟** |$1.60 |**$1,298** |★★☆ 중단 가능한 |**크루소 클라우드** |$2.00 |**$1,622** |★★★★ 신뢰할 수 있는 데이터센터 |유동 스택 |$1.98 |$1 606 |★★★ |TensorDock |$1.80 |$1 460 |★★☆ |런팟 |$2.29 |$1 857 |★★★ 좋은 타협 |코어웨이브 |$2.25 |$1 825 |★★★★ 기업 |람다 랩스 |$2.49 |$2 019 |★★★★ 프리미엄 |=== [TIP] ==== Vast.ai spot은 가장 저렴하지만, tus runs(실행) 은 언제든지 중단될 수 있습니다. 학습에는 위험합니다. 시간당 $2.00인 Crusoe은 신뢰성 대비 가격 측면에서 최적입니다. Vast와의 차액 $324는 마음의 평화를 가질 가치가 있습니다. ==== === Wall-clock : 전체를 훈련시키는 데 얼마나 걸리나요? 단일 3× H100 노드만 사용하면 31개의 실행(1개 범용 + 30개 전문가)은 약**12일**순차적으로. 2개의 노드를 병렬로 임대하면, 다음과 같이 떨어집니다.**6일**. 실제로, 마이크로 전문가는 별도의 노드(각각 1 H100)에서 실행될 수 있으며, V4-Flash는 3× H100 노드를 점유합니다. 지능적인 스케줄링을 통해 : ---- Nœud A (3× H100) : V4-Flash généraliste → V4-Flash experts ×5 (11 jours) Nœud B (1× H100) : Gemma 4 26B ×6 → Qwen 36 ×5 → Qwen 35 ×5 (6 jours) 7일간 대여, 모두 접혀 있습니다. == 추론: Ollama Cloud에서 23개 모델, 월 17유로부터 시작 이것은 건축의 가장 우아한 부분입니다. Ollama Cloud에서는 Pro 플랜 기능으로 비공개 모델을 업로드할 수 있습니다. 내 22개의 파인튜닝된 모델은 ... 로_push되고 있습니다.`.gguf`내 Ollama 공간에 있으며, 비공개로 표시되어 있고, 표준 API를 통해 접근할 수 있습니다. [plantuml, inference-flow, svg] ---- @startuml skinparam backgroundColor #FAFAFA skinparam defaultFontSize 12 |Utilisateur| start :Tâche de développement; |Orkestrateur (V4-Pro)| :Classifier la tâche\n(domaine + complexité); if (Tâche simple,\nspécialisée ?) then (oui) :Router vers micro-expert\n(Gemma 4 26B-A4B-FT\n ou Qwen3.6-35B-A3B-FT); elseif (Tâche complexe,\nconventions fortes ?) then (oui) :Router vers exécutif\n(V4-Flash-FT); else (non) :Résoudre avec V4-Pro\n(architecture, décision); endif |Modèle ciblé| :Génère le code/output\n**dans mon style**,\n90%+ first-shot correct; :Retourne la réponse; stop @enduml ---- === 월 17유로부터 시작하며, 필요 시 확장합니다. Ollama Pro 플랜 (연간 17유로/월)은 3개의 경쟁 클라우드 모델을 허용합니다. 이 아키텍처에서는 동시에 2-3명 이상의 전문가가 필요하지 않습니다. * (V4-Pro) 분류 단계는 1 슬롯을 차지하며, 몇 초 정도 소요됩니다. * 대상 전문가는 1개의 슬롯을 차지하며, 응답을 생성하는 데 걸리는 시간 * 3번째 슬롯은 병렬 작업을 위해 예약되어 있습니다. 사용량이 증가하면, xref:0120_cumuler_deux_abonnements_ollama_pro_docker_post.adoc[구독 합산에 대한 내 글]에서 설명한 Docker 방법을 통해 추가 Pro 계정을 추가합니다. 월 100유로 Max 플랜은 없습니다 — 실제로 필요한 것만 추가합니다. 유일한 제한 요인은**GPU 시간 할당량**Ollama 월간(무료 플랜 대비 50배 Pro 플랜). 저는 하루에 몇백 건 정도 사용하기에 충분합니다. [IMPORTANT] ==== V4-Pro (49B 활성화) 호출의 마진 비용과 Gemma 4 26B-A4B (3.8B 활성화) 비교 시의 비용은**나에게조차도: 0**. 이건 Ollama 플랜이 compute 차이를 흡수하는 것입니다. 내 유일한 지표는 지연 시간입니다. ==== === 라우팅 실무</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre></pre> </div> </div> <div class="paragraph"> <p>Volume de requêtes estimé : ~500/jour</p> </div> <div class="paragraph"> <p>├─ 50% → Gemma 4 26B-A4B-FT (micro, 3.8B actifs) │ Formatage AsciiDoc, scripts simples, conventions nommage │ ├─ 25% → V4-Flash-FT (exécutif, 13B actifs) │ Plugins Gradle, refactoring Kotlin, génération DAG │ ├─ 15% → Qwen 35B MoE-FT (micro, 3B actifs) │ Tâches intermédiaires, review de code, documentation │ └─ 10% → V4-Pro (orkestrateur, 49B actifs) Décisions architecturales, refactoring transverse, problèmes vraiment nouveaux</p> </div> <div class="listingblock"> <div class="content"> <pre>트래픽의 대부분이 작은 것을 통해 흐릅니다. 큰 모델은 최후의 수단으로만 개입한다. == 아픈 비교 : Claude, GPT, Gemini, Grok vs 내 함대 이곳에서 격차가 급격히 벌어집니다. 같은 양의 작업(하루 500건의 요청, 평균적으로 입력 300 토큰 + 출력 2,000 토큰)이 2026년 5월 시장의 독점 솔루션으로 얼마나 드는지 살펴봅시다. === Anthropic — Claude (2026년 5월 요금) Anthropic는 최근 가격 *인하*를 단행했습니다. DeepSeek과 Qwen과 같은 오픈 웨이트 솔루션의 압력이 느껴지고 있습니다. [cols="3,2,2,2,2"] |=== |모델 |$/MTok |$/MTok |비용/일 |**월 비용** |Opus 4.7 (가장 지능적인) |$5 |$25 |$25.75 |**$772** |소네트 4.6 (균형 잡힌) |$3 |$15 |$15.45 |**$463** |Haiku 4.5 (가장 빠른) |$1 |$5 |$5.15 |**154달러** |=== [CAUTION] ==== 이 요금은 *후* Anthropic의 마지막 가격 인하(2026년 5월) 이후의 것입니다. 그 이전에는 Opus가 MTok당 $15/$75였습니다. 오픈-웨이트에 대한 두려움은 현실입니다. ==== Claude의 가장 저렴한 모델조차 — Haiku 4.5에**154€/월**— 17유로의 Ollama Pro 구독료보다 9배 더 비쌉니다. 그리고 Haiku는 내 코드베이스를 알지 못하며, 내 스타일로 생성하지도 않고, 체계적인 프롬프트 엔지니어링이 필요합니다. 가장 똑똑한 — Opus 4.7 — 예산을 초과하는**772유로/월**하루에 500건 정도의 소규모 요청량에 대해. 즉**45배 더 비싸다**그 내 해결책. === OpenAI — GPT (2026년 5월 요금) [cols="3,2,2,2,2"] |=== |모델 |$/MTok |출력 $/MTok |비용/일 |**월 비용** |GPT 5.5 (가장 똑똑한) |$5 |$30 |$30.90 |**$927** |GPT 5.4 (표준) |$2.50 |$15 |$15.45 |**$463** |GPT 5.4 미니 |$0.75 |$4.50 |$4.64 |**$139** |=== OpenAI의 « 경제적 » 모델인 GPT 5.4 Mini(월 139유로)조차도 내 구독료의 8배에 달하며, 내 규칙에 대해 *rien* 을 아는 바가 없고, 무거운 프롬프트 엔지니어링이 필요합니다. GPT 5.5, 그들의 주력 제품 :**927유로/월**. *zero-shot*을 내 코드베이스에. 스타일이 미숙하여 작업당 2-3번의 반복이 필요하면, 실제 월간 비용이 쉽게 두 배로 늘어납니다. === Google — Gemini (2026년 5월 요금) [cols="3,2,2,2,2"] |=== |모델 |$/MTok |$/MTok |일당 비용 |**비용/월** |Gemini 3.1 Pro (고급) |$3.50 |$17.50 |$18.00 |**540달러** |Gemini 3.1 Pro |$2 |$10 |$10.30 |**$309** |제미니 3 플래시 |$0.30 |$1.50 |$1.54 |**46달러** |=== Gemini 3 Flash 월 46유로는 순수 가격 면에서 경쟁력이 있지만 — 하지만 파인튜닝 없이, 일반적 코드를 생성합니다. *Cheroliv* 코드가 아닙니다. === Grok — xAI (2026년 5월 요금) [cols="3,2,2,2,2"] |=== |모델 |$/MTok |$/MTok |일일 비용 |**월 비용** |그록 4 |$4 |$16 |$16.48 |**$494** |그로크 4 미니 |$0.80 |$3.20 |$3.30 |**$99** |=== === Microsoft — Azure OpenAI (2026년 5월 요금) Azure는 직접 OpenAI API와 동일한 가격을 적용하지만, 인프라와 네트워크 비용을 추가로 청구합니다. 관리형 서비스에 대해 10-20%의 추가 비용을 예상해야 합니다. [cols="3,2,2,2,2"] |=== |모델 |$/MTok |$/MTok |비용/일 |**월 비용** |GPT 5.4 (Azure, 글로벌) |$2.50 |$15 |$15.45 |**$463** |GPT 5.4 + 인프라스트럭처 |15% 추가 비용 |15%의 추가 비용 |$17.77 |**$533** |=== [NOTE] ==== 위에 명시된 요금은 API용이며, '채팅' 구독은 아닙니다(Claude Pro 월 $20, ChatGPT Plus 월 $20). 여기서 비교하는 것은 개발자 사용법이며, 이는 하루에 수백 건의 요청을 API를 통해 이어서 생성, 리팩터링, 문서화를 하는 경우입니다. 일반 사용자 구독은 500 요청/일 이전에 할당량이 빠르게 소진됩니다. ==== === 최종 비교 표 [cols="3,2,2,2,2,2"] |=== |해결 |지식 코드베이스 |통합된 스타일 |비용/개월 |반복 |**실제 비용** |**내 함대 (Ollama Pro)** |✅ 세부 조정된 |무게에서 |**17유로** |0-1 |**17유로** |클로드 오퍼스 4.7 |❌ 제로 샷 |❌ 필요한 프롬프트 |$772 |2-3 |$1 500-2 300 |클로드 하이쿠 4.5 |❌ 제로샷 |필요한 프롬프트 |$154 |3-4 |$460-615 |GPT 5.5 |❌ Zero-shot |❌ 필요한 프롬프트 |$927 |2-3 |$1 854-2 781 |GPT 5.4 |❌ 제로샷 |필요한 프롬프트 |$463 |2-3 |$925-1 390 |GPT 5.4 미니 |❌ 제로샷 |❌ 필수 프롬프트 |$139 |3-5 |$417-695 |제미니 3.1 프로 하이 |❌ 제로 샷 |필요한 프롬프트 |$540 |2-3 |$1 080-1 620 |Grok 4 |제로샷 |❌ 필수 프롬프트 |$494 |2-3 |$988-1 482 |**애저 GPT 5.4** |❌ 제로샷 |❌ 필요한 프롬프트 |$533 |2-3 |$1 066-1 600 |=== [plantuml, cost-comparison, svg]</pre> </div> </div> <div class="paragraph"> <p>@startuml skinparam backgroundColor #FAFAFA</p> </div> <div class="paragraph"> <p>title 비용 효율성 보고서 — 내 함대 대 시장 (2026년 5월) rectangle "17유로/월" as OURS #4ECDC4 rectangle "Opus 4.7 772€" as OPUS #FF6B6B rectangle "Sonnet 4.6 463유로" as SONNET #FF8B94 rectangle "GPT 5.5\n927€" as GPT #FFD93D rectangle "Gemini 3.1 Pro\n540€" as GEMINI #6C5CE7 rectangle "Grok 4 494유로" as GROK #A8E6CF rectangle "Haiku 4.5 154유로" as HAIKU #DFE6E9 rectangle "GPT 5.4 Mini 139€" as MINI #B2BEC3</p> </div> <div class="paragraph"> <p>note bottom of OURS Avec fine-tune intégré. Zéro prompt engineering. 90%+ first-shot correct. end note</p> </div> <div class="paragraph"> <p>@enduml</p> </div> <div class="listingblock"> <div class="content"> <pre>미세조정된 AI 전문가 23명에게 월 17유로. Claude Opus 4.7 플래그십은 비용이 듭니다.**45배 더 비싸다**내 *mon* 코드베이스에 낮은 품질로. GPT 5.5의 비용은**54배 더 비싸다**. 가장 저렴한 모델조차 (Gemini Flash 46유로) 비용이 발생한다**2.7배 더**내 워크스페이스를 알지 못한 채. 판단은 확정적이다: 2026년 MoE 아키텍처에 대한 파인튜닝은 단순히 « 더 저렴한 » 것이 아니다. 이것은 효율성의 요인이다**27×에서 54×까지**비용 대비 품질 비율에서 독점 솔루션과 비교할 때. Anthropic, OpenAI, Google — 모두가 이것을 알고 있으며, 그래서 그들은 패닉에 빠져 가격을 내리고 있다. == 효율 인자: 5-8× vs V4-Pro 단독 사용 두 극단을 비교해 봅시다. === 시나리오 A : V4-Pro 단독으로 모든 것 [cols="3,2"] |=== |미터법 |가치 |코드베이스에 대한 지식 |0 (제로샷) |협약 명명 |40-60% 첫 시도 정확한 |필요한 프롬프트 엔지니어링 |예, 체계적인 |작업당 반복 |2-3 |인퍼런스 비용 |$100/월 (Ollama Max) |평균 지연 |~20 tok/s + 네트워크 |=== === 시나리오 B : 오케스트레이션된 MoE 함대 [cols="3,2"] |=== |미터법 |값 |코드베이스 지식 |통합된(세밀 조정된) |명명 규칙 |90-95%가 첫 시도에서 정확함 |프롬프트 엔지니어링 |아니요 (스타일은 가중치에 있습니다) |작업당 반복 횟수 |0-1 |추론 비용 |$60/월 (3배 Ollama Pro) |평균 지연 |~50 tok/초 (경량 모델) |=== [cols="4,2,2,2"] |=== |차원 |V4-Pro만 |함대 MoE |우편배달부 |월간 클라우드 비용 |$100 |**$60** |1.7× |주입할 컨텍스트 |높은 (prompt) |**영** |∞ |평균 반복 횟수 |2-3 |**0-1** |2-3× |느껴지는 지연 |초당 20토큰 |50 tok/s |**2.5배** |첫 번째 샷이 정확합니다 |50% |90%+ |**1.8×** |=== **전체 효율 인자 : 5-8×**— 개발자 생산성에서 느끼는 [NOTE] ==== 요인은 토큰이나 달러로 측정되지 않는다. 그것은 « 모델에게 이미 알고 있어야 할 것을 설명하는 데 내가 쓰는 시간 »으로 측정된다. 파인튜닝된 모델에서는 이 시간이 0에 수렴한다. ==== == 전체 예산 : 일회성 투자, 터무니없는 패키지 [cols="3,2"] |=== |직책 |금액 |학습 GPU (811 H100-h, Crusoe $2/h) |**$1,622** |합성 데이터셋 생성 (LLM API) |**400달러** |추론 (Ollama Pro 연간, $17/월) |**$204** |**첫 해 총계** |**$2 226** |**월 등가** |**$186** |**쿼리당 예상 비용** |< $0.01 |=== [plantuml, budget-breakdown, svg]</pre> </div> </div> <div class="paragraph"> <p>@startuml skinparam backgroundColor #FAFAFA</p> </div> <div class="paragraph"> <p>rectangle "예산 1년차: $2 226" as Total #E8E8E8 { rectangle "GPU 훈련 $1 622 (73%)" as Train #FF6B6B rectangle "데이터셋 증류 $400 (18%)" as Data #FFE66D rectangle "Ollama Pro $204 (9%)" as Cloud #4ECDC4 }</p> </div> <div class="paragraph"> <p>note bottom of Total $186/mois équivalent année 1. Dès l’an 2 : $17/mois. Amorti par ~$235 de CA mensuel avec marge 95%. end note</p> </div> <div class="paragraph"> <p>@enduml</p> </div> <div class="listingblock"> <div class="content"> <pre>$186/월 첫해,**$17/월**2년 차부터, 넷플릭스 프리미엄 구독 가격, 24시간 7일 가용한 23명의 AI 전문가 팀을 위해, 그들이 *내 스타일*로 코드를 작성하는 데 내가 그들에게 내 규칙을 설명할 필요가 없이. === 수익성 계산 edster.cloud와 약 95%의 마진을 가지고, 손익분기점은**~$2 340 추가 CA**연간. 실제로는 : * 1 소프트웨어 파일럿 미션 → $3 000-5 000 → 투자금 회수 + 이익 * 1 기업 교육 → $5 000-10 000 → 편안한 * 암시적인 업셀 : "내 AI 팀이 내 소프트웨어 공장을 장악한다" → 상업적 차별화 2년 차부터는 트레이닝 비용을 더 이상 지불할 필요가 없습니다(데이터셋 업데이트 제외). 연간 비용이 떨어집니다**$204**($17/월). 비용 대비 가치 비율은 유니콘과 같다 : 거의 없음. == 운동의 한계 이것은 여전히 *대략적인 추정*입니다. 여러 변수가 예산 변동을 일으킬 수 있습니다: [cols="2,3"] |=== |변수 |영향 |합성 데이터셋 생성 |증류 API가 엉망이면(환각, 잘못된 쌍) 인간 시간을 들여 정리해야 합니다. 숨은 비용. |Ollama GPU 시간 할당량 |사용량이 프로 플랜 할당량을 초과하면 플랜을 업그레이드하거나 전용 GPU로 전환해야 합니다. |파인 튜닝의 실제적인 품질 |실패한 파인튜닝 → 다시 해야 함. 진짜 위험은 하이퍼파라미터이며, GPU 위치가 아님. |모델의 빠른 진화 |Qwen3.6/Gemma 4는 1개월 미만 전에 출시되었습니다. 6개월 후 다음 세대는 더 좋고 파인튜닝하기에 더 저렴할 것입니다. |=== [WARNING] ==== 단일 마이크로 모델에서 파이프라인을 먼저 테스트하지 않고 811시간의 학습을 시작하지 마세요. Qwen 35B-A3B에서 3-4시간 실행은 $8 비용이 듭니다. 데이터셋이 망가졌다면 $8로 알 수 있고, $1,622로는 알 수 없습니다. ==== == 결론 : 파인튜닝이 접근 가능한 럭셔리가 되었습니다. 1년 전, 292B 파라미터 모델을 파인튜닝하는 것(QLoRA를 사용하더라도)은 연구에 해당했습니다. 오늘날, 2026년 5월, 이는 독립 개발자에게 가능한 프로젝트가 되었습니다: * **811 H100-시간**트레이닝의 — $1,622 크루소에서 * **23개의 특화된 모델**Ollama Cloud에 로드됨 —**$17/개월** * **0 서버, 0 로컬 GPU, 0 유지보수 인프라** 민주화는 세 가지 수렴하는 요인에서 비롯되었다: 1. **MoE 아키텍처**— 효과적으로 fine-tuning할 수 있게 해 주는, 가중치의 일부만 활성화된 모델들 2. **Ollama Cloud의 고정 플랜**— 변동 비용(per-token)을 고정 비용(abonnement)으로 바꾸는 3. **고품질 오픈-웨이트 모델**— DeepSeek V4, Qwen3.6, Gemma 4는 MIT/Apache 2.0 라이선스 하에 있습니다. 문명은 우리가 생각하지 않고 수행할 수 있는 중요한 작업의 수를 늘림으로써 발전한다. 파인튜닝, 그게 바로 그것이야: 기계를 위임해서 더 이상 신경을 쓰지 않아도 되는 작업이지. 그리고 2026년에는 신입 개발자 월급보다 저렴해. --- _게시된 글 {jbake-date}_ == 함대의 미세 조정된 모델 [cols="2,2,2,2,3"] |=== |활성화된 크기 |숫자 |기본 모델 |도메인 |데이터셋 |13B |1 |디프시크-V4-플래시-베이스 |일반 워크스페이스 |50M 토큰 |13B |5 |딥시크-V4-플래시 |그레이들, 코틀린, DAG, 문서, 인프라 |15M 토큰 |3.8B |6 |Gemma 4 26B-A4B |마이크로 작업, 포맷팅, 스크립트 |5M 토큰 |3B |5 |Qwen3.6-35B-A3B |리팩터링, 리뷰, 중간 문서 |5M 토큰 |3B |5 |Qwen3.5-35B-A3B |레거시 작업, 호환성 |5백만 토큰 |=== == 자원 === HuggingFace의 open-weight 모델 * https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash-Base[DeepSeek V4-Flash-Base — 292B 파라미터, 라이선스 MIT] * https://huggingface.co/Qwen/Qwen3.6-35B-A3B[Qwen3.6-35B-A3B — 35B/3B 활성화됨, 라이선스 Apache 2.0] * https://huggingface.co/Qwen/Qwen3.5-35B-A3B[Qwen3.5-35B-A3B — 35B/3B 활성화된, Apache 2.0 라이선스] * https://huggingface.co/google/gemma-4-26B-A4B-it[Gemma 4 26B-A4B — 26B/3.8B 활성화된, Apache 2.0 라이선스] === 요금 출처 (2026년 5월) * https://ollama.com/pricing[Ollama Cloud 요금제 — Pro 플랜 $17/월 연간] * https://www.anthropic.com/pricing[Anthropic 요금 — Claude API (Opus 4.7 $5/$25, Sonnet 4.6 $3/$15, Haiku 4.5 $1/$5)] * https://openai.com/api/pricing/[OpenAI 요금 — GPT API (GPT 5.5 $5/$30, GPT 5.4 $2.50/$15)] * https://deepinfra.com/pricing[DeepInfra 요금 — GPU 인스턴스 H100 $1.79/h, B200 $2.79/h] * Vast.ai, Crusoe Cloud, FluidStack, TensorDock, RunPod, CoreWeave, Lambda Labs — 수동 가격 기록, 2026년 5월 === 공식 발표 * https://qwen.ai/blog?id=qwen3.6-35b-a3b[공식 발표 Qwen3.6-35B-A3B — Qwen 블로그]— 에이전틱 코딩, Apache 2.0, 262K 컨텍스트</pre> </div> </div> </div> </div> https://cheroliv.com/blog/2026/0121_plugin_gradle_piloter_deux_instances_ollama_pro_post.html Fri, 8 May 2026 00:00:00 +0000 blog/2026/0121_plugin_gradle_piloter_deux_instances_ollama_pro_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_소개">소개</a></li> <li><a href="#_왜_인프라에_gradle를_사용해야_할까요">왜 인프라에 Gradle를 사용해야 할까요?</a></li> <li><a href="#_전체_build_gradle_kts">전체 build.gradle.kts</a></li> <li><a href="#_핵심_업무의_해부">핵심 업무의 해부</a> <ul class="sectlevel2"> <li><a href="#_startollamab_런처">startOllamaB` — 런처</a></li> <li><a href="#_signinb_대화형">signInB` — 대화형</a></li> <li><a href="#_pullmodelb_조정_가능한">pullModelB` — 조정 가능한</a></li> <li><a href="#_statusollamaall_진단">statusOllamaAll` — 진단</a></li> <li><a href="#_cleanollamab_정체성을_보존하는_청소">cleanOllamaB` — 정체성을 보존하는 청소</a></li> </ul> </li> <li><a href="#_완전한_워크플로우_제로에서_두_세션까지">완전한 워크플로우 — 제로에서 두 세션까지</a></li> <li><a href="#_왜_이것을_진짜_gradle_플러그인으로_만들지_않을까요">왜 이것을 진짜 Gradle 플러그인으로 만들지 않을까요 ?</a></li> <li><a href="#_배운_교훈">배운 교훈</a></li> <li><a href="#_결론">결론</a></li> <li><a href="#_자원">자원</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽기 시간 : 18 minutes</div> <p>도커 명령어를 직접 입력할 필요가 있나요? 모든 것을 Gradle 작업에 캡슐화할 수 있는데요. 외부 셸 스크립트 없이 내 듀얼-Ollama Pro 설정을 산업화한 방법을 보여드리겠습니다. 시작, 중지, 식별, 로그인, 풀 — 모든 것이`./gradlew`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_소개">소개</h2> <div class="sectionbody"> <div class="paragraph"> <p>이전 글에서는 Ollama Pro 계정 두 개를 동일한 머신에서 공존시키기 위해 두 번째 인스턴스를 Docker 컨테이너에 격리하는 방법을 보여 주었습니다. 설정은 작동하지만 일상적인 관리가 빨리 번거로워집니다: 컨테이너 이름을 기억하고 올바른 명령을 다시 실행해야 합니다.<code>docker exec</code>, checker 어떤 포트가 활성화되어 있는지…​</p> </div> <div class="paragraph"> <p>당신은 14개의 터미널이 열려 있는 순간, 그때 입력하고 있는 것을 알고 있죠`docker exec ollama-instance-b ollama list`네 번째로, 그리고 당신은 « 더 깨끗한 방법이 반드시 있어야 해 »라고 생각하나요?</p> </div> <div class="paragraph"> <p>이 방법이 그레이들입니다.</p> </div> <div class="paragraph"> <p>코드를 빌드하는 것만이 아니다. Gradle은 로컬 인프라스트럭처의 지휘자처럼. 프로비저닝, 검증, 테스트, 정리를 수행하는 작업들. 모두가 하나의 …​에 버전 관리됨.<code>build.gradle.kts`옆에 사는`docker-compose.yml</code>.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml !theme plain skinparam handwritten false skinparam shadowing false skinparam BoxPadding 8 skinparam DefaultFontSize 11 skinparam ArrowThickness 1.5 left to right direction actor "개발자" as Dev package "build.gradle.kts" as GradleFile { usecase "OllamaB 시작" as Start usecase "stopOllamaB" as Stop usecase "신원 확인" as Check usecase "signInB" as SignIn usecase "pullModelB" as Pull usecase "testOllamaB" as Test usecase "statusOllamaAll" as Status usecase "cleanOllamaB" as Clean } package "Docker 데몬" as DockerDaemon { node "ollama-instance-b" as ContainerB { component ":11435" as Port database "~/ollama-b-data" as Volume } } package "Ollama 네이티브" as Native { component ":11434" as NatPort } Dev --> Start Dev --> SignIn Dev --> Pull Dev --> Test Dev --> Status Dev --> Check Dev --> Stop Dev --> Clean Start ..> ContainerB : docker run -d Stop ..> ContainerB : docker stop Check ..> Volume : cat id_ed25519.pub SignIn ..> ContainerB : ollama signin Pull ..> ContainerB : ollama pull Test ..> ContainerB : curl /v1/chat/completions Status ..> ContainerB : docker ps Status ..> Native : curl :11434 Clean ..> ContainerB : docker rm -f note bottom of GradleFile Zéro script bash externe. Tout est dans le build.gradle.kts, versionné avec le projet. end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_왜_인프라에_gradle를_사용해야_할까요">왜 인프라에 Gradle를 사용해야 할까요?</h2> <div class="sectionbody"> <div class="paragraph"> <p>질문은 정당합니다. Gradle은 빌드 도구입니다. 보통, 그것은 컴파일하고, 테스트하고, 패키징합니다. 그것은 Docker 컨테이너를 실행하지 않습니다.</p> </div> <div class="paragraph"> <p>그런데 Gradle는 의존성 그래프 엔진이기도 해서, 여기서 흥미로워지는 부분이 우리 경우에 적용됩니다.</p> </div> <div class="paragraph"> <p>우리는 원한다 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>컨테이너가 로그인 전에 실행되도록</p> </li> <li> <p>모델 풀 전에 신원이 확인되어야 합니다</p> </li> <li> <p>컨테이너가 다운되면 API 테스트가 조용히 실패합니다</p> </li> </ol> </div> <div class="paragraph"> <p>순수한 의존성 그래프에서. Gradle은 그에 맞게 설계되었습니다. Kotlin DSL은 태스크 작성을 유연하게 만들고, 그리고`doLast`시스템 명령어를 애플리케이션 코드처럼 실행할 수 있게 해줍니다.</p> </div> <div class="paragraph"> <p>그리고 무엇보다: 유지할 bashrc도 없고, 나뒹구는 스크립트도 없으며`~/bin`, docker-compose 옆에 Makefile이 없습니다. 모든 것이 하나의 파일에 있으며, 프로젝트 코드와 같은 위치에 있습니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_전체_build_gradle_kts">전체 build.gradle.kts</h2> <div class="sectionbody"> <div class="paragraph"> <p>이게 내가 결국 작성한 파일이예요. 볼륨 프로비저닝부터 검증 curl까지, 대화형 로그인을 거치며 모든 과정을 처리합니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">import java.io.ByteArrayOutputStream plugins { base } // ------------------------------------------------------------------------- // Configuration // ------------------------------------------------------------------------- val instanceName = "ollama-instance-b" val instancePort = 11435 val instanceImage = "ollama/ollama:0.20.2" val dataDir = file("${System.getProperty("user.home")}/ollama-b-data") val nativePort = 11434 // Modèles à gérer — cloud Pro + un modèle local gratuit pour les tests val proModels = listOf("deepseek-v4-pro:cloud", "gemma4:31b-cloud") val freeModels = listOf("qwen3:0.6b") // ------------------------------------------------------------------------- // Tâche préparatoire — création du volume si absent // ------------------------------------------------------------------------- val prepareVolume by tasks.registering { group = "ollama" description = "Crée le répertoire de volume pour l'instance B si absent" doLast { if (!dataDir.exists()) { dataDir.mkdirs() println("Volume créé : ${dataDir.absolutePath}") } else { println("Volume existant : ${dataDir.absolutePath}") } } } // ------------------------------------------------------------------------- // Démarrage du conteneur Docker // ------------------------------------------------------------------------- val startOllamaB by tasks.registering(Exec::class) { group = "ollama" description = "Lance le conteneur Docker pour l'instance Ollama B" dependsOn(prepareVolume) commandLine( "docker", "run", "-d", "--name", instanceName, "-p", "$instancePort:11434", "-v", "${dataDir.absolutePath}:/root/.ollama", "-e", "OLLAMA_HOST=0.0.0.0", "--restart", "always", instanceImage ) isIgnoreExitValue = true doLast { val alreadyRunning = executionResult.get().exitValue != 0 if (alreadyRunning) { logger.lifecycle("Le conteneur '$instanceName' existe déjà — tentative de démarrage") } else { logger.lifecycle("Conteneur '$instanceName' lancé") } } } // ------------------------------------------------------------------------- // Arrêt du conteneur // ------------------------------------------------------------------------- val stopOllamaB by tasks.registering(Exec::class) { group = "ollama" description = "Arrête le conteneur Docker de l'instance B" commandLine("docker", "stop", instanceName) isIgnoreExitValue = true doLast { logger.lifecycle("Conteneur '$instanceName' arrêté") } } // ------------------------------------------------------------------------- // Affichage de la clé publique (Device Key) // ------------------------------------------------------------------------- val checkIdentity by tasks.registering(Exec::class) { group = "ollama" description = "Affiche la clé publique SSH de l'instance B" dependsOn(startOllamaB) commandLine("docker", "exec", instanceName, "cat", "/root/.ollama/id_ed25519.pub") standardOutput = ByteArrayOutputStream() doLast { val pubKey = standardOutput.toString().trim() println("=".repeat(60)) println("Device Key (Instance B)") println("=".repeat(60)) println(pubKey) println("=".repeat(60)) println("→ Enregistre cette clé sur https://ollama.com/settings/keys") println("→ Puis exécute : ./gradlew signInB") println("=".repeat(60)) } } // ------------------------------------------------------------------------- // Sign-in interactif (Ouvrira le navigateur) // ------------------------------------------------------------------------- val signInB by tasks.registering(Exec::class) { group = "ollama" description = "Lance l'authentification interactive Ollama pour le compte B" dependsOn(startOllamaB) standardInput = System.`in` standardOutput = System.out errorOutput = System.err commandLine("docker", "exec", "-it", instanceName, "ollama", "signin") doFirst { logger.lifecycle("Authentification pour le Compte Pro B...") logger.lifecycle("Ouvre ton navigateur et connecte-toi avec l'email du compte B") } } // ------------------------------------------------------------------------- // Pull d'un modèle (paramétrable via propriété Gradle) // ------------------------------------------------------------------------- val pullModelB by tasks.registering(Exec::class) { group = "ollama" description = "Pull un modèle sur l'instance B. Usage : ./gradlew pullModelB -Pmodel=nom:tag" dependsOn(startOllamaB) val modelName = project.findProperty("model") as? String ?: "qwen3:0.6b" commandLine("docker", "exec", instanceName, "ollama", "pull", modelName) doFirst { logger.lifecycle("Pull du modèle '$modelName' sur l'instance B...") } doLast { logger.lifecycle("Modèle '$modelName' pullé avec succès") } } // ------------------------------------------------------------------------- // Pull de tous les modèles Pro (batch) // ------------------------------------------------------------------------- val pullAllProModels by tasks.registering { group = "ollama" description = "Pull tous les modèles cloud Pro sur l'instance B" dependsOn(startOllamaB) doLast { proModels.forEach { model -> logger.lifecycle("→ Pull $model...") val process = ProcessBuilder("docker", "exec", instanceName, "ollama", "pull", model) .inheritIO() .start() process.waitFor() } logger.lifecycle("Tous les modèles Pro pullés") } } // ------------------------------------------------------------------------- // Pull de tous les modèles gratuits (batch / première install) // ------------------------------------------------------------------------- val pullAllFreeModels by tasks.registering { group = "ollama" description = "Pull tous les modèles locaux gratuits sur l'instance B" dependsOn(startOllamaB) doLast { freeModels.forEach { model -> logger.lifecycle("→ Pull $model...") val process = ProcessBuilder("docker", "exec", instanceName, "ollama", "pull", model) .inheritIO() .start() process.waitFor() } logger.lifecycle("Tous les modèles gratuits pullés") } } // ------------------------------------------------------------------------- // Liste des modèles disponibles sur l'instance B // ------------------------------------------------------------------------- val listModelsB by tasks.registering(Exec::class) { group = "ollama" description = "Liste les modèles disponibles sur l'instance B" dependsOn(startOllamaB) commandLine("docker", "exec", instanceName, "ollama", "list") } // ------------------------------------------------------------------------- // Health check — test API sur les deux instances // ------------------------------------------------------------------------- val testOllamaB by tasks.registering { group = "ollama" description = "Teste la connectivité API de l'instance B avec un simple chat" dependsOn(startOllamaB) doLast { val model = project.findProperty("model") as? String ?: "qwen3:0.6b" logger.lifecycle("Test de l'instance B avec le modèle '$model'...") val payload = """ { "model": "$model", "messages": [{"role": "user", "content": "Réponds uniquement par OK"}], "max_tokens": 5 } """.trimIndent() val process = ProcessBuilder( "curl", "-s", "http://localhost:$instancePort/v1/chat/completions", "-H", "Content-Type: application/json", "-d", payload ).start() val response = process.inputStream.bufferedReader().readText() process.waitFor() if (response.contains("\"id\":\"chatcmpl") || response.contains("\"choices\"")) { println("✓ Instance B OK — port $instancePort répond") println(" Response: ${response.take(120)}...") } else { println("✗ Instance B INACTIVE — vérifie le conteneur avec './gradlew statusOllamaAll'") println(" Raw: $response") } } } // ------------------------------------------------------------------------- // Health check sur les deux instances simultanément // ------------------------------------------------------------------------- val statusOllamaAll by tasks.registering { group = "ollama" description = "Vérifie le statut des deux instances Ollama (native + Docker)" doLast { // Instance native runCatching { val process = ProcessBuilder( "curl", "-s", "-o", "/dev/null", "-w", "%{http_code}", "http://localhost:$nativePort/api/tags" ).start() val code = process.inputStream.bufferedReader().readText().trim() process.waitFor() println(if (code == "200") "✓ Instance Native — port $nativePort OK (HTTP $code)" else "✗ Instance Native — port $nativePort (HTTP $code)") }.getOrElse { println("✗ Instance Native — injoignable sur le port $nativePort") } // Instance Docker runCatching { val process = ProcessBuilder( "curl", "-s", "-o", "/dev/null", "-w", "%{http_code}", "http://localhost:$instancePort/api/tags" ).start() val code = process.inputStream.bufferedReader().readText().trim() process.waitFor() println(if (code == "200") "✓ Instance Docker B — port $instancePort OK (HTTP $code)" else "✗ Instance Docker B — port $instancePort (HTTP $code)") }.getOrElse { println("✗ Instance Docker B — injoignable sur le port $instancePort") } // Info conteneur runCatching { val process = ProcessBuilder("docker", "ps", "--filter", "name=$instanceName", "--format", "table {{.Names}}\\t{{.Status}}\\t{{.Ports}}").start() val status = process.inputStream.bufferedReader().readText() process.waitFor() println() println("Conteneur Docker :") println(status) } } } // ------------------------------------------------------------------------- // Nettoyage complet // ------------------------------------------------------------------------- val cleanOllamaB by tasks.registering(Exec::class) { group = "ollama" description = "Arrête et supprime le conteneur Docker de l'instance B" dependsOn(stopOllamaB) commandLine("docker", "rm", instanceName) isIgnoreExitValue = true doLast { logger.lifecycle("Conteneur '$instanceName' supprimé") logger.lifecycle("Le volume ${dataDir.absolutePath} est conservé (identité persistante)") } } // ------------------------------------------------------------------------- // Affichage des instructions // ------------------------------------------------------------------------- val helpOllama by tasks.registering { group = "ollama" description = "Affiche l'aide des tâches Ollama disponibles" doLast { println(""" ╔══════════════════════════════════════════════════════════════╗ ║ Tâches Gradle — Pilotage Dual Ollama Pro ║ ╠══════════════════════════════════════════════════════════════╣ ║ ./gradlew startOllamaB Démarrer l'instance Docker B ║ ║ ./gradlew stopOllamaB Arrêter l'instance Docker B ║ ║ ./gradlew checkIdentity Afficher la clé SSH publique ║ ║ ./gradlew signInB Sign-in interactif compte B ║ ║ ./gradlew pullModelB Pull un modèle (-Pmodel=...) ║ ║ ./gradlew pullAllProModels Pull tous les modèles Pro ║ ║ ./gradlew pullAllFreeModels Pull tous les modèles gratuits ║ ║ ./gradlew listModelsB Lister les modèles instance B ║ ║ ./gradlew testOllamaB Test API avec un chat simple ║ ║ ./gradlew statusOllamaAll Santé des 2 instances ║ ║ ./gradlew cleanOllamaB Supprimer le conteneur ║ ║ ./gradlew helpOllama Cette aide ║ ╚══════════════════════════════════════════════════════════════╝ """.trimIndent()) } }</code></pre> </div> </div> <div class="paragraph"> <p>자. 열두 가지 작업, 하나의 진입점, 그리고 마찰이 전혀 없습니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_핵심_업무의_해부">핵심 업무의 해부</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_startollamab_런처">startOllamaB` — 런처</h3> <div class="paragraph"> <p>별거 아냐 : 하나`docker run -d`올바른 매개변수와 함께. 비결은`isIgnoreExitValue = true`.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">isIgnoreExitValue = true</code></pre> </div> </div> <div class="paragraph"> <p>컨테이너가 이미 존재하면 명령`docker run`실패합니다 (exit code ≠ 0). 이 속성이 없으면 Gradle은 전체 빌드를 오류로 중단합니다. 여기서 실패는 조용합니다 — 그리고`doLast`이미 존재하는"인지 진짜 오류인지 감지합니다.</p> </div> <div class="paragraph"> <p>Le `doLast`그는 명령어 실행 후에 <strong>après</strong> 실행된다, 이로 인해 검사할 수 있게 된다`executionResult.get().exitValue`그리고 적절한 메시지를 로그합니다.</p> </div> </div> <div class="sect2"> <h3 id="_signinb_대화형">signInB` — 대화형</h3> <div class="paragraph"> <p>이것은 인간의 상호작용이 필요한 유일한 작업입니다. Gradle은 전송합니다.`System.in`프롬프트가 되도록 프로세스에`ollama signin`정상적으로 표시될 수 있도록 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">standardInput = System.`in` standardOutput = System.out errorOutput = System.err</code></pre> </div> </div> <div class="paragraph"> <p>그렇지 않으면 stdin이 닫혀서 sign-in이 차단될 것이고, 프롬프트를 결코 볼 수 없을 것입니다.</p> </div> </div> <div class="sect2"> <h3 id="_pullmodelb_조정_가능한">pullModelB` — 조정 가능한</h3> <div class="paragraph"> <p>일반적인 작업이 매개변수를 받는 것을 통해`-P` :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./gradlew pullModelB -Pmodel=deepseek-v4-pro:cloud ./gradlew pullModelB # fallback : qwen3:0.6b</code></pre> </div> </div> <div class="paragraph"> <p>폴백은 중요합니다 :`project.findProperty("model") as? String ?: "qwen3:0.6b"`매개변수가 누락되면 작업이 실패하지 않음을 보장한다</p> </div> </div> <div class="sect2"> <h3 id="_statusollamaall_진단">statusOllamaAll` — 진단</h3> <div class="paragraph"> <p>두`curl`항구에서의 건강`11434` et <code>11435</code>, fallback을(를) 사용하는`runCatching`다운된 인스턴스가 있어도 크래시되지 않도록. 출력은 구조화되어 있습니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">✓ Instance Native — port 11434 OK (HTTP 200) ✓ Instance Docker B — port 11435 OK (HTTP 200) Conteneur Docker : NAMES STATUS PORTS ollama-instance-b Up 3 hours 0.0.0.0:11435->11434/tcp</code></pre> </div> </div> <div class="paragraph"> <p>한 번 쳐다보면, 정확히 무엇이 돌아가고, 무엇이 잘못됐는지 알 수 있다.</p> </div> </div> <div class="sect2"> <h3 id="_cleanollamab_정체성을_보존하는_청소">cleanOllamaB` — 정체성을 보존하는 청소</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">commandLine("docker", "rm", instanceName) isIgnoreExitValue = true</code></pre> </div> </div> <div class="paragraph"> <p>컨테이너는 삭제되었지만 볼륨은`~/ollama-b-data`이다<strong>보존된</strong>. SSH 신원은 정리를 견딘다. 다음에`startOllamaB`, 동일한 키가 재사용됩니다 — sign‑in을 다시 할 필요도 없고 Device Key를 다시 등록할 필요도 없습니다.</p> </div> <div class="admonitionblock caution"> <table> <tr> <td class="icon"> <i class="fa icon-caution" title="🔒"></i> </td> <td class="content"> <div class="paragraph"> <p><code>cleanOllamaB`볼륨을 건드리지 마세요. 당신이 B의 정체성을 삭제하고(다시 처음부터 시작하고 싶다면) 삭제해야 합니다</code>~/ollama-b-data`수동으로. 이것은 자발적인 — un`clean`는 자격 증명을 파괴해서는 안 됩니다.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_완전한_워크플로우_제로에서_두_세션까지">완전한 워크플로우 — 제로에서 두 세션까지</h2> <div class="sectionbody"> <div class="paragraph"> <p>다음은 프로젝트에 참여하여 문서를 열지 않고 모든 것을 설정하려는 사람을 위한 이상적인 시퀀스입니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text"># 1. Premier contact — que faire ? $ ./gradlew helpOllama # 2. On démarre l'instance B $ ./gradlew startOllamaB # 3. On récupère la Device Key et on l'enregistre sur ollama.com $ ./gradlew checkIdentity # → copier-coller de la clé sur https://ollama.com/settings/keys # 4. Authentification interactive $ ./gradlew signInB # 5. Pull d'un petit modèle gratuit pour tester la plomberie $ ./gradlew pullModelB # 6. Test API $ ./gradlew testOllamaB # 7. Si tout est vert, pull des modèles Pro $ ./gradlew pullAllProModels # 8. Vérification finale des deux instances $ ./gradlew statusOllamaAll</code></pre> </div> </div> <div class="paragraph"> <p>2분도 채 안 되어 모든 것이 프로비저닝됩니다. 읽을 README도 없고, 설정할 환경 변수도 없습니다. 작업`helpOllama`내장된 설명서 역할을 합니다.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml !theme plain skinparam DefaultFontSize 11 actor Développeur as Dev participant "Gradle\n(build.gradle.kts)" as Gradle participant "Docker Daemon" as Docker participant "Ollama 인스턴스 B" as OllamaB participant "Ollama 클라우드" as Cloud == Provisionnement == Dev -> Gradle : helpOllama Gradle --> Dev : Aide et instructions Dev -> Gradle : startOllamaB Gradle -> Docker : docker run -d ollama/ollama:0.20.2 Docker -> OllamaB : Génération clés SSH (id_ed25519) Docker --> Gradle : conteneur lancé Gradle --> Dev : OK Dev -> Gradle : checkIdentity Gradle -> Docker : cat id_ed25519.pub Gradle --> Dev : Clé publique SSH Dev -> Cloud : Enregistrement clé SSH\n(sur ollama.com/settings/keys) == Authentification == Dev -> Gradle : signInB Gradle -> Docker : ollama signin (interactif) Dev <-> Cloud : Login navigateur (compte B) Docker -> Cloud : Échange token ⇔ Device Key Gradle --> Dev : Authentifié == Vérification == Dev -> Gradle : pullModelB Gradle -> Docker : ollama pull qwen3:0.6b Gradle --> Dev : Modèle pullé Dev -> Gradle : testOllamaB Gradle -> Docker : curl /v1/chat/completions Gradle --> Dev : ✓ Instance B OK == Production == Dev -> Gradle : pullAllProModels Gradle -> Docker : ollama pull deepseek-v4-pro:cloud Gradle -> Docker : ollama pull gemma4:31b-cloud Gradle --> Dev : Modèles Pro pullés Dev -> Gradle : statusOllamaAll Gradle --> Dev : ✓ Native ✓ Docker B @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_왜_이것을_진짜_gradle_플러그인으로_만들지_않을까요">왜 이것을 진짜 Gradle 플러그인으로 만들지 않을까요 ?</h2> <div class="sectionbody"> <div class="paragraph"> <p>정당한 질문. 이를 추출`build.gradle.kts`독립적인 Gradle 플러그인이라면 다음과 같은 장점이 있습니다: 프로젝트 간 재사용, 선언적 구성, DSL 확장.</p> </div> <div class="paragraph"> <p>하지만 지금은 의미가 없습니다. 이 빌드에는 복잡한 비즈니스 로직이 없습니다 — 이는 Docker 및 curl 명령을 둘러싼 래퍼일 뿐입니다. 완전한 Gradle 플러그인(확장, 단위 테스트, publish 포함)의 추가 계층은 12개의 유틸리티 작업에 비해 과도할 것입니다.</p> </div> <div class="paragraph"> <p>Le `build.gradle.kts`inline는 필요한 프로젝트에 존재한다. 다른 곳에 복사하기는 매우 간단하다. 만약 언젠가 세 개의 프로젝트가 이에 의존하게 된다면, 나는 이를 플러그인으로 바꿀 것이다. 지금은 KISS.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> <div class="paragraph"> <p>세 개를 가진 날`build.gradle.kts`세 프로젝트에서 동일한 코드가 반복될 때, 플러그인을 추출해야 한다는 신호입니다. 그 전에, 중복이 추상화보다 비용이 적게 듭니다. 개발자의 지혜.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_배운_교훈">배운 교훈</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Gradle은 단순한 빌드 도구가 아니다.</strong>— 의존성 그래프 엔진 덕분에 이는 두려울 정도로 강력한 인프라 오케스트레이터가 된다.<code>doLast</code>, <code>isIgnoreExitValue</code>, <code>dependsOn</code>: 이 세 가지 원시 기능은 CI 파이프라인과 동일한 신뢰성으로 Docker 컨테이너를 제어하는 데 충분합니다.</p> </li> <li> <p><strong>isIgnoreExitValue`는 네 친구야</strong>— 이상적인 세계에서,<code>docker run`이미 존재하는 컨테이너에 대해 실행하면 오류 종료 코드 대신 경고가 반환됩니다. 실제 상황에서 너는`isIgnoreExitValue = true`그리고 너는 진단을 관리하고 있는`doLast</code>.</p> </li> <li> <p><strong>구성 가능한 작업은 모호함을 없앤다</strong> — Un <code>pullModelB`제네릭과 함께</code>-Pmodel=…​`N개의 전문 작업을 대체합니다. 하나의 작업, 하나의 문서, 하나의 동작.</p> </li> <li> <p><strong>runCatching` 헬스 체크를 위해</strong>— N개의 엔드포인트를 테스트할 때, 첫 번째의 크래시가 다른 것을 테스트하는 것을 막아서는 안 된다.<code>runCatching</code>+`getOrElse`엔드포인트당이며, 부분적인 장애가 발생해도 진단은 여전히 완전합니다.</p> </li> <li> <p><strong>helpOllama` 작업을 실행 가능한 문서처럼</strong> — Un `println()`잘 포맷된 형식은 세 문단짜리 README를 대체합니다. 자동 문서화되어 있으며, 항상 최신 상태를 유지하고 터미널을 나가지 않고도 접근할 수 있습니다.</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_결론">결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>수동으로 입력해야 했던 Docker 명령어에서 완전하고 버전 관리되고 재사용 가능한 Gradle 워크플로우로 전환했습니다. 12개의 작업이 전체 수명 주기를 포괄합니다: 프로비저닝, 아이덴티티, 로그인, pull, 테스트, 진단, 정리.</p> </div> <div class="paragraph"> <p>docker-compose + build.gradle.kts + opencode.json 조합은 깔끔한 삼위일체를 이룹니다: Docker는 격리를 위해, Gradle은 오케스트레이션을 위해, OpenCode는 소비를 위해 사용됩니다. 각 레이어는 각각의 책임을 가지고 있으며, 어느 하나도 다른 영역을 침범하지 않습니다.</p> </div> <div class="paragraph"> <p>다음 단계? CI에서 라이프사이클을 자동화하여 임시 개발 환경에서 Ollama 인스턴스를 사용할 수 있게 하는 것입니다. 하지만 이건 또 다른 글입니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_자원">자원</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://docs.gradle.org/current/userguide/tutorial_using_tasks.html">사용자 매뉴얼 Gradle — 작업</a></p> </li> <li> <p><a href="https://docs.gradle.org/current/userguide/custom_tasks.html">Gradle 사용자 매뉴얼 — 커스텀 작업</a></p> </li> <li> <p><a href="https://hub.docker.com/r/ollama/ollama">Docker Hub의 Ollama Docker 이미지</a></p> </li> <li> <p><a href="https://kotlinlang.org/docs/gradle.html">Gradle DSL Kotlin — 문서</a></p> </li> </ul> </div> <hr> <div class="paragraph"> <p><em>게시된 기사 2026-05-08</em></p> </div> </div> </div> https://cheroliv.com/blog/2026/0120_cumuler_deux_abonnements_ollama_pro_docker_post.html Fri, 8 May 2026 00:00:00 +0000 blog/2026/0120_cumuler_deux_abonnements_ollama_pro_docker_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_소개">소개</a></li> <li><a href="#_왜_두_번_같은_것인가요">왜 두 번 같은 것인가요?</a></li> <li><a href="#_문제의_핵심_디바이스_키">문제의 핵심: 디바이스 키</a></li> <li><a href="#_준비_단계별로">준비 — 단계별로</a> <ul class="sectlevel2"> <li><a href="#_선행_조건">선행 조건</a></li> <li><a href="#_단계_1_볼륨_생성">단계 1 : 볼륨 생성</a></li> <li><a href="#_단계_2_도커_컨테이너_실행">단계 2: 도커 컨테이너 실행</a></li> <li><a href="#_단계_3_공개_키를_가져오기">단계 3: 공개 키를 가져오기</a></li> <li><a href="#_4단계_ollama_com에_키_저장하기">4단계: Ollama.com에 키 저장하기</a></li> <li><a href="#_단계_5_작은_무료_모델로_테스트하기">단계 5 : 작은 무료 모델로 테스트하기</a></li> </ul> </li> <li><a href="#_api_함정_v1models">API 함정 `/v1/models</a></li> <li><a href="#_결과_두_세션_두_계정_갈등_없음">결과 : 두 세션, 두 계정, 갈등 없음</a></li> <li><a href="#_배운_교훈">배운 교훈</a></li> <li><a href="#_더_나아가기">더 나아가기</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽는 데 걸리는 시간 : 14 minutes</div> <p>두 개의 Pro 구독, 한 대의 기계, 한 장의 신용카드, 그리고 네트워크 충돌 없음. Docker가 두 번째 PC를 구매하지 않고도 내 클라우드 추론 용량을 두 배로 늘릴 수 있도록 해준 방법.</p> </div> </div> </div> <div class="sect1"> <h2 id="_소개">소개</h2> <div class="sectionbody"> <div class="paragraph"> <p>저는 Ollama Pro를 몇 달 동안 사용해 왔으며, 이를 통해 OpenCode 세션에 클라우드 모델을 공급하고 있습니다. 문제는, Pro 구독을 가지고 있더라도 동시에 여러 에이전트를 실행하면 <strong>rate limiting</strong> 때문에 금방 제한에 걸린다는 점입니다. 명백한 해결책: 두 번째 구독.</p> </div> <div class="paragraph"> <p>그런데 거기서는 비극이야.</p> </div> <div class="paragraph"> <p>Ollama는 각 머신을 고유한 SSH 키로 식별합니다 — 유명한 <strong>Device Key</strong>. 같은 OS 상의 두 인스턴스는 동일한 정체성을 공유하게 되며, 동일한 기기에 두 개의 Pro 계정을 연결하는 것은 불가능합니다. 그리고 예상하셨겠지만, 저는 단순히 그것을 위해 두 번째 랩톱을 구매하지는 않을 겁니다.</p> </div> <div class="paragraph"> <p>해결책: 속임수. Ollama에게 두 대의 다른 기계에서 실행되고 있다고 믿게 하다, 사실 같은 CPU, 같은 RAM, 같은 네트워크 연결을 공유하고 있다. 도커는 우리에게 완벽한 격리 버블을 제공할 것이다.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml !theme plain skinparam BoxPadding 10 skinparam DefaultFontSize 12 left to right direction node "물리적 기계" { frame "Ollama 인스턴스 A (네이티브)" as Native { database "신원 /usr/share/ollama/.ollama/id_ed25519" as KeyA portin "API\n:11434" as PortA } frame "Ollama 인스턴스 B (Docker)" as Docker { database "정체성 ~/ollama-b-data/id_ed25519" as KeyB portin "API :11435" as PortB } } cloud "올라마 클라우드" { actor "프로 A 계정 (이메일 1)" as AccountA actor "프로 B 계정 (이메일 2)" as AccountB } KeyA --> AccountA : "SSH 키 A" KeyB --> AccountB : "SSH 키 B" PortA --> AccountA : "요청 A" PortB --> AccountB : "요청 B" note bottom of Docker Conteneur isolé : identité SSH distincte, port réseau distinct, volume persistant end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_왜_두_번_같은_것인가요">왜 두 번 같은 것인가요?</h2> <div class="sectionbody"> <div class="paragraph"> <p>정신병 환자라고 부르기 전에, 사용 사례를 설명해 드리겠습니다.</p> </div> <div class="paragraph"> <p>하나의 Pro 구독만 있으면 모델을 실행할 수 있어`deepseek-v4-pro:cloud`OpenCode 세션에서. 문제가 <strong>두</strong> 개의 동시 세션을 원할 때 발생합니다. Rate limiting quotas 때문에 두 번째 세션이 느려지거나 완전히 거부됩니다.</p> </div> <div class="paragraph"> <p>두 개의 독립된 Pro 구독:</p> </div> <div class="ulist"> <ul> <li> <p>세션 OpenCode 1 → 프로 계정 A`localhost:11434`)</p> </li> <li> <p>세션 OpenCode 2 → 계정 프로 B (<code>localhost:11435</code>)</p> </li> </ul> </div> <div class="paragraph"> <p>각 세션은 자체 할당량과 자체 컨텍스트를 가지고 있으며, 서로 방해하지 않습니다. 이것은 인간의 멀티프로세싱입니다.</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>두 개의 Pro 구독 = 서로 다른 두 개의 이메일. 동일한 은행 카드가 작동합니다 — Ollama 결제 시스템은 동일한 결제 수단에서 여러 구독을 차단하지 않습니다. 저는 확인했습니다.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_문제의_핵심_디바이스_키">문제의 핵심: 디바이스 키</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ollama를 설치하면, ed25519 SSH 키 쌍이 identity 디렉터리에 생성됩니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ cat /usr/share/ollama/.ollama/id_ed25519.pub ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...</code></pre> </div> </div> <div class="paragraph"> <p>이 키는 Ollama 서버로 업로드됩니다 동안의`ollama signin`. 그녀가 이렇게 말한다: « 이 기계는 해당 Pro 계정에 속합니다 ». 두 인스턴스가 같은 파일을 공유하면`id_ed25519`, 그들은 같은 정체성을 공유합니다. 게임 끝.</p> </div> <div class="paragraph"> <p>퍼레이드: 우리 두 번째 인스턴스에 자체 ID 디렉터리를 제공하고, 이를 Docker 볼륨에 격리합니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_준비_단계별로">준비 — 단계별로</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_선행_조건">선행 조건</h3> <div class="ulist"> <ul> <li> <p>기능적인 네이티브 Ollama 설치 (공식 스크립트`curl | sh`)</p> </li> <li> <p>도커가 설치되어 작동 중</p> </li> <li> <p>배포를 위한 Portainer 또는 docker-compose</p> </li> <li> <p>두 개의 Ollama 계정, 두 개의 다른 이메일 주소</p> </li> </ul> </div> <div class="paragraph"> <p>나는 버전을 사용했다`0.20.2`— 공식 스크립트가 제공하는 것과 해당하는 Docker 이미지.</p> </div> </div> <div class="sect2"> <h3 id="_단계_1_볼륨_생성">단계 1 : 볼륨 생성</h3> <div class="paragraph"> <p>호스트의 간단한 디렉터리가 인스턴스 B의 ID에 대한 영구 볼륨으로 사용됩니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">mkdir -p ~/ollama-b-data</code></pre> </div> </div> <div class="paragraph"> <p>이 폴더는 Docker 컨테이너에 마운트될 것입니다.<code>/root/.ollama</code>, Ollama가 신원 키, 기록 및 모델을 저장하는 곳.</p> </div> </div> <div class="sect2"> <h3 id="_단계_2_도커_컨테이너_실행">단계 2: 도커 컨테이너 실행</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml"># docker-compose.yml services: ollama-instance-b: image: ollama/ollama:0.20.2 container_name: ollama-instance-b ports: - "11435:11434" volumes: - /home/cheroliv/ollama-b-data:/root/.ollama environment: - OLLAMA_HOST=0.0.0.0 restart: always</code></pre> </div> </div> <div class="paragraph"> <p>여기서 일어나는 일 :</p> </div> <div class="ulist"> <ul> <li> <p>항구<strong>11435</strong>호스트의 …​에 매핑됨<strong>11434</strong>컨테이너 내부. 따라서 Docker 인스턴스는 에서 수신 대기합니다.<code>:11435`네이티브 인스턴스가 점유하고 있는 것과 충돌 없이</code>:11434`.</p> </li> <li> <p>볼륨`~/ollama-b-data`장착된`/root/.ollama`— 여기서 SSH 신분이 저장됩니다.</p> </li> <li> <p>`OLLAMA_HOST=0.0.0.0`컨테이너가 외부 연결을 수락할 수 있게 합니다.</p> </li> </ul> </div> <div class="paragraph"> <p>나는 Portainer를 통해 이 스택을 배포했지만, 간단한`docker compose up -d`같은 방식으로도 잘 작동합니다.</p> </div> </div> <div class="sect2"> <h3 id="_단계_3_공개_키를_가져오기">단계 3: 공개 키를 가져오기</h3> <div class="paragraph"> <p>컨테이너가 처음 시작할 때 비어 있으므로, Ollama는 볼륨 내에서 새 SSH 키 쌍을 자동으로 생성합니다. 공개 키를 가져옵니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ docker exec ollama-instance-b cat /root/.ollama/id_ed25519.pub ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDDQ+dvnfmuo49q5O8LOlvgZ39SKORFw47ry9k4H2jPc</code></pre> </div> </div> <div class="paragraph"> <p>저는 이 키가 기본 인스턴스의 키와 <strong>다른</strong> 것을 확인합니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Instance native $ cat /usr/share/ollama/.ollama/id_ed25519.pub ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGyF...(différente) # Instance Docker $ cat ~/ollama-b-data/id_ed25519.pub ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDDQ...(différente)</code></pre> </div> </div> <div class="paragraph"> <p>두 개의 서로 다른 열쇠, 두 개의 별개 정체성. 다 끝났어.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> <div class="paragraph"> <p>컨테이너가 다시 시작되면, 그것은 *재사용*하는 볼륨에 있는 키를 재사용합니다. 정체성은 지속됩니다. Pro 계정과의 연관을 잃지 않을 것입니다.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_4단계_ollama_com에_키_저장하기">4단계: Ollama.com에 키 저장하기</h3> <div class="paragraph"> <p>지시 <a href="https://ollama.com/settings/keys" class="bare">https://ollama.com/settings/keys</a> → SSH 키 추가. Docker 인스턴스의 공개 키를 붙여넣고 확인합니다.</p> </div> <div class="paragraph"> <p>그다음에, 이 신분을 Pro B 계정에 연결합니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ docker exec -it ollama-instance-b ollama signin</code></pre> </div> </div> <div class="paragraph"> <p>브라우저가 열립니다, 계정 B의 이메일로 로그인합니다, 그리고 토큰은 컨테이너의 SSH 키와 연결됩니다. 모든 것이 정상인지 확인합니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ docker exec -it ollama-instance-b ollama signin User: cherolivpro</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_단계_5_작은_무료_모델로_테스트하기">단계 5 : 작은 무료 모델로 테스트하기</h3> <div class="paragraph"> <p>프로 구독 가격을 얘기하기 전에, 파이프가 잘 작동하는지 확인하고 싶어요. 연결성을 검증하기 위해 작은 로컬 무료 모델을 pull합니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ docker exec ollama-instance-b ollama pull qwen3:0.6b pulling manifest pulling 7f4030143c1c: 100% ▕██████████████████▏ 522 MB success $ curl -s http://localhost:11435/api/tags {"models":[{"name":"qwen3:0.6b","model":"qwen3:0.6b",...}]}</code></pre> </div> </div> <div class="paragraph"> <p>항구`11435`답하고, 모델은 제공됩니다. 인스턴스 B는 살아 있습니다.</p> </div> <div class="paragraph"> <p>안심하고 나서, 나는 진짜 클라우드 프로 모델의 풀로 넘어간다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ docker exec ollama-instance-b ollama pull deepseek-v4-pro:cloud pulling manifest pulling 31c3059e137e: 100% ▕██████████████████▏ 344 B success</code></pre> </div> </div> <div class="paragraph"> <p>클라우드 모델의 매니페스트가 344 바이트 — 정상입니다. 추론은 로컬이 아닌 서버 쪽에서 이루어집니다. 그리고 이것이 궁극적인 테스트입니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ curl -s http://localhost:11435/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"deepseek-v4-pro:cloud","messages":[{"role":"user","content":"Dis bonjour en une phrase courte."}]}' { "id": "chatcmpl-480", "model": "deepseek-v4-pro", "choices": [{ "message": { "content": "Bonjour !" }, "finish_reason": "stop" }], "usage": { "total_tokens": 181 } }</code></pre> </div> </div> <div class="paragraph"> <p>B 인스턴스도 안녕하세요.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_api_함정_v1models">API 함정 `/v1/models</h2> <div class="sectionbody"> <div class="paragraph"> <p>바보 같은 디테일에 20분을 허비했다. provider를 설정했을 때`ollama-b`OpenCode에서는 모델 선택기에 아무것도 나타나지 않았습니다. 아무것도요. 전혀 없었어요.</p> </div> <div class="paragraph"> <p>이유는? API`/v1/models`인스턴스 B에서 돌아가고 있었다`{"object":"list","data":null}`대신에`{"object":"list","data":[]}`어떤 모델도 끌어오지 않았을 때. 값`null`OpenCode 측에서 파싱을 중단시켰고, 제공자를 표시하지 않았습니다.</p> </div> <div class="paragraph"> <p>솔루션: OpenCode 구성에서 모델을 <strong>명시적으로</strong> 선언하고 동적 탐색에 의존하지 않는 것입니다.</p> </div> <div class="listingblock"> <div class="title">~/.config/opencode/opencode.json</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{ "$schema": "https://opencode.ai/config.json", "provider": { "ollama": { "npm": "@ai-sdk/openai-compatible", "name": "Ollama (local)", "options": { "baseURL": "http://localhost:11434/v1" }, "models": { "gemma4:e2b": { "name": "Gemma 4 E2B (local)" } } }, "ollama-b": { "npm": "@ai-sdk/openai-compatible", "name": "Ollama Instance B (Docker)", "options": { "baseURL": "http://localhost:11435/v1" }, "models": { "qwen3:0.6b": { "name": "Qwen3 0.6B (B)" }, "deepseek-v4-pro:cloud": { "name": "DeepSeek V4 Pro (B)" } } } } }</code></pre> </div> </div> <div class="paragraph"> <p>이 명시적 선언과 함께, OpenCode는 즉시 provider B와 그 모델을 확인합니다. 세션을 재시작하고, 셀렉터`/models`두 인스턴스를 나란히 표시합니다.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>사용자 지정 공급자를 보지 못하면`/models`, 세 시간 동안 터미널을 재시작하는 데 시간을 낭비하지 마세요. 수동으로 모델을 선언하세요 안에`opencode.json`— 이것이 문제를 즉시 해결합니다.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_결과_두_세션_두_계정_갈등_없음">결과 : 두 세션, 두 계정, 갈등 없음</h2> <div class="sectionbody"> <div class="paragraph"> <p>결국, 저는 두 개의 OpenCode 세션을 동시에 시작할 수 있습니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">Session 1 → /models → Ollama (local) → deepseek-v4-pro:cloud → Compte A Session 2 → /models → Ollama Instance B (Docker) → deepseek-v4-pro:cloud → Compte B</code></pre> </div> </div> <div class="paragraph"> <p>각 세션마다 자체 할당량과 자체 레이트 제한이 있으며 서로 간섭하지 않습니다. 같은 기기, 같은 신용카드, 두 개의 다른 이메일.</p> </div> <div class="paragraph"> <p>그리고 가장 좋은 점은? Docker 컨테이너는 진행 중`restart: always`. 시스템 재부팅에도 수동 개입 없이 살아남습니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_배운_교훈">배운 교훈</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Docker는 모든 것을 격리합니다, 심지어 정체성까지도</strong>— 볼륨에 대한 간단한 바인드 마운트만으로도 컨테이너에 자체 SSH 키 세트를 제공할 수 있어, Ollama 입장에서는 물리적으로 다른 기계와 구분되지 않는다.</p> </li> <li> <p><strong>두 개의 이메일, 동일한 CB</strong>— Ollama는 동일한 결제 수단으로부터 여러 구독을 차단하지 않습니다. 이메일만 달라야 합니다.</p> </li> <li> <p><strong>무료로 테스트해보다 결제하기</strong> — Un <code>ollama pull qwen3:0.6b</code> (modèle libre, 522 Mo) permet de valider toute la chaîne réseau sans débourser un centime. Vous validez le plomberie d’abord, vous activez le Pro ensuite.</p> </li> <li> <p><strong>/v1/models`와 <code>data: null`은 OpenCode을 깨뜨립니다.</strong>— 커스텀 제공자를 구성하면`"models": {}</code>, OpenCode는 API를 통해 모델을 발견하려고 시도합니다. 만약 API가 응답하면`data: null`, provider가 나타나지 않습니다. 모델을 명시적으로 선언하세요.</p> </li> <li> <p><strong>두 개의 계정은 인간 다중 처리다.</strong>— Pro 계정 = 활성화된 OpenCode 세션. 두 개의 계정 = 두 개의 병렬 세션. 여러 Gradle 프로젝트를 동시에 다루는 사람에게 이것은 게임 체인저입니다.</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_더_나아가기">더 나아가기</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://ollama.com/settings/keys">Ollama 설정 — SSH 키 관리</a></p> </li> <li> <p><a href="https://docs.ollama.com/">Ollama 공식 문서</a></p> </li> <li> <p><a href="https://hub.docker.com/r/ollama/ollama">Docker Hub의 Docker Ollama 이미지</a></p> </li> <li> <p><a href="https://opencode.ai/docs/providers/#ollama">OpenCode — Ollama 구성 공급자</a></p> </li> </ul> </div> <hr> <div class="paragraph"> <p>게시일: 2026-05-08</p> </div> </div> </div> https://cheroliv.com/blog/2025/0080_kitty_term_post.html Thu, 7 May 2026 00:00:00 +0000 blog/2025/0080_kitty_term_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_왜_kitty와_zsh를_선택해야_할까요">왜 Kitty와 Zsh를 선택해야 할까요?</a></li> <li><a href="#_시스템_사전_요구사항">시스템 사전 요구사항</a></li> <li><a href="#_kitty_다운로드_및_설치">Kitty 다운로드 및 설치</a> <ul class="sectlevel2"> <li><a href="#_설치_스크립트를_다운로드하세요">설치 스크립트를 다운로드하세요</a></li> <li><a href="#_심볼릭_링크_생성">심볼릭 링크 생성</a></li> </ul> </li> <li><a href="#_xubuntu에_kitty_통합">Xubuntu에 Kitty 통합</a> <ul class="sectlevel2"> <li><a href="#_데스크톱_파일을_복사">데스크톱 파일을 복사</a></li> <li><a href="#_데스크톱_파일_수정">데스크톱 파일 수정</a></li> <li><a href="#_kitty를_기본_터미널로_설정_선택_사항">Kitty를 기본 터미널로 설정 (선택 사항)</a></li> </ul> </li> <li><a href="#_zsh_설치">Zsh 설치</a></li> <li><a href="#_zsh를_기본_셸로_설정">Zsh를 기본 셸로 설정</a> <ul class="sectlevel2"> <li><a href="#_전역_방법_모든_터미널에_대해">전역 방법 (모든 터미널에 대해)</a></li> <li><a href="#_kitty_전용_방법">Kitty 전용 방법</a></li> </ul> </li> <li><a href="#_zsh_구성_선택_사항">Zsh 구성 (선택 사항)</a> <ul class="sectlevel2"> <li><a href="#_파일_zshrc_생성">파일 .zshrc 생성</a></li> <li><a href="#_최소_구성_예시">최소 구성 예시</a></li> </ul> </li> <li><a href="#_완전한_워크플로_요약">완전한 워크플로 요약</a></li> <li><a href="#_최종_검증">최종 검증</a> <ul class="sectlevel2"> <li><a href="#_구성_파일_열기">📂 구성 파일 열기</a></li> <li><a href="#_️_추가하거나_수정_font_size">🖋️ 추가하거나 수정 `font_size</a></li> <li><a href="#_저장하고_kitty_다시_시작">💾 저장하고 Kitty 다시 시작</a></li> <li><a href="#_동적_조정_임시_줌">✅ 동적 조정 (임시 줌)</a></li> </ul> </li> <li><a href="#_oh_my_zsh_설치_및_구성">Oh My Zsh 설치 및 구성</a> <ul class="sectlevel2"> <li><a href="#_oh_my_zsh_설치">Oh My Zsh 설치</a></li> <li><a href="#_테마_변경">테마 변경</a></li> <li><a href="#_검증">검증</a></li> <li><a href="#_유스_케이스_다이어그램">유스 케이스 다이어그램</a></li> </ul> </li> <li><a href="#_kitty에서_투명도_활성화">Kitty에서 투명도 활성화</a> <ul class="sectlevel2"> <li><a href="#_투명성을_위한_사전_조건">투명성을 위한 사전 조건</a></li> <li><a href="#_kitty_conf에서_투명도_구성">kitty.conf에서 투명도 구성</a></li> <li><a href="#_kitty_재시작">Kitty 재시작</a></li> <li><a href="#_가능한_보완">가능한 보완</a></li> <li><a href="#_시퀀스_다이어그램_kitty_투명도_초기화">시퀀스 다이어그램 - Kitty 투명도 초기화</a></li> <li><a href="#_알려진_제한">알려진 제한</a></li> </ul> </li> <li><a href="#_벨_소리_비활성화_청각적_벨">벨 소리 비활성화 (청각적 벨)</a></li> <li><a href="#_kitty_업데이트">Kitty 업데이트</a></li> <li><a href="#_참고문헌">참고문헌</a></li> <li><a href="#_결론">결론</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>이 가이드는 Xubuntu에서 <strong>kitty</strong> 터미널을 단계별로 설치하고 올바르게 구성하며, bash를 기본 셸로 *zsh*로 바꾸는 방법을 설명합니다. kitty 프로젝트는 여기에서 이용할 수 있습니다: <a href="https://github.com/kovidgoyal/kitty" class="bare">https://github.com/kovidgoyal/kitty</a>.</p> </div> <div class="paragraph"> <p><em>__</em> Kitty는 요구가 높은 개발자에게 특히 적합한 현대적이고 빠르며 구성 가능한 터미널입니다. (empty)</p> </div> </div> </div> <div class="sect1"> <h2 id="_왜_kitty와_zsh를_선택해야_할까요">왜 Kitty와 Zsh를 선택해야 할까요?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Kitty은(는) 다음과 같이 특징이 있습니다:</p> </div> <div class="ulist"> <ul> <li> <p>GPU 가속 덕분에 향상된 성능,</p> </li> <li> <p>단일 텍스트 파일을 기반으로 완전히 구성된,</p> </li> <li> <p>폰트와 리가처에 대한 훌륭한 지원</p> </li> </ul> </div> <div class="paragraph"> <p>Zsh는 그에 반해 강력한 인터랙티브 셸을 제공합니다:</p> </div> <div class="ulist"> <ul> <li> <p>지능형 완성,</p> </li> <li> <p>맞춤형 프롬프트,</p> </li> <li> <p>bash와 높은 호환성.</p> </li> </ul> </div> <div class="paragraph"> <p>Kitty와 Zsh를 함께 사용하면 생산적이고 미적인 환경을 누릴 수 있습니다.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml title 간소화된 아키텍처 Kitty + Zsh actor User User --> Kitty : Lance le terminal Kitty --> Zsh : Initialise le shell interactif Zsh --> System : Interagit avec le système (fichiers, commandes) @enduml</pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>이 가이드는 스크립트를 통한 설치와 Xubuntu에만 의도적으로 제한됩니다.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_시스템_사전_요구사항">시스템 사전 요구사항</h2> <div class="sectionbody"> <div class="paragraph"> <p>시작하기 전에, 가지고 있어야 할 것 :</p> </div> <div class="ulist"> <ul> <li> <p>Xubuntu 설치됨,</p> </li> <li> <p>인터넷 접속,</p> </li> <li> <p>스크립트를 실행하기 위한 기능적인 bash 셸</p> </li> </ul> </div> <div class="paragraph"> <p>환경을 확인하세요:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">uname -a lsb_release -a</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_kitty_다운로드_및_설치">Kitty 다운로드 및 설치</h2> <div class="sectionbody"> <div class="paragraph"> <p>Kitty는 공식 스크립트를 통해 파일을 설치하는 것을 권장합니다. 파일을 넣는`~/.local/kitty.app`.</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="Important"></i> </td> <td class="content"> <div class="paragraph"> <p>이 방법은 패키지 관리자에 독립적인(없는`apt`).</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_설치_스크립트를_다운로드하세요">설치 스크립트를 다운로드하세요</h3> <div class="paragraph"> <p>다음 명령어를 실행하세요:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh /dev/stdin</code></pre> </div> </div> <div class="paragraph"> <p>이 명령은 수행합니다 :</p> </div> <div class="ulist"> <ul> <li> <p>바이너리 다운로드,</p> </li> <li> <p>추출에서`~/.local/kitty.app`,</p> </li> <li> <p>심볼릭 링크 생성.</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre>@startuml title Kitty 다운로드 및 설치 start :curl -L installer.sh; :sh /dev/stdin; :Décompression dans ~/.local/kitty.app; :create symlinks; stop @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_심볼릭_링크_생성">심볼릭 링크 생성</h3> <div class="paragraph"> <p>소환하기 위해`kitty`터미널에서 심볼릭 링크를 생성하세요 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">ln -s ~/.local/kitty.app/bin/kitty ~/.local/bin/kitty</code></pre> </div> </div> <div class="paragraph"> <p>추가하세요`~/.local/bin`votre PATH에 추가하지 않았다면 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc source ~/.zshrc</code></pre> </div> </div> <div class="paragraph"> <p>설치를 확인할 수 있습니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">kitty --version</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_xubuntu에_kitty_통합">Xubuntu에 Kitty 통합</h2> <div class="sectionbody"> <div class="paragraph"> <p>Kitty가 응용 프로그램 메뉴에 나타나도록:</p> </div> <div class="sect2"> <h3 id="_데스크톱_파일을_복사">데스크톱 파일을 복사</h3> <div class="paragraph"> <p>파일을 복사하세요`.desktop`제공 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">cp ~/.local/kitty.app/share/applications/kitty.desktop ~/.local/share/applications/</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_데스크톱_파일_수정">데스크톱 파일 수정</h3> <div class="paragraph"> <p>파일을 편집하세요 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">nano ~/.local/share/applications/kitty.desktop</code></pre> </div> </div> <div class="paragraph"> <p>다음 줄을 확인하거나 수정하세요:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">[Desktop Entry] Version=1.0 Type=Application Name=Kitty Terminal Comment=Fast GPU-based terminal emulator Exec=/home/$USER/.local/kitty.app/bin/kitty Icon=kitty Categories=System;TerminalEmulator;</code></pre> </div> </div> <div class="paragraph"> <p>바꿔`YOURUSER`사용자 이름으로</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml title Xubuntu 메뉴에 Kitty 통합 프로세스 start :Copier .desktop; :Editer les chemins; :Sauvegarder; :Menu Applications; stop @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_kitty를_기본_터미널로_설정_선택_사항">Kitty를 기본 터미널로 설정 (선택 사항)</h3> <div class="paragraph"> <p>Kitty가 기본 터미널로 실행되도록 하려면:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo update-alternatives --install /usr/bin/x-terminal-emulator x-terminal-emulator ~/.local/kitty.app/bin/kitty 50 sudo update-alternatives --config x-terminal-emulator</code></pre> </div> </div> <div class="paragraph"> <p>선택하세요`kitty`제안된 메뉴에서.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_zsh_설치">Zsh 설치</h2> <div class="sectionbody"> <div class="paragraph"> <p>Zsh가 아직 설치되지 않았다면, 실행하세요 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install zsh</code></pre> </div> </div> <div class="paragraph"> <p>설을 확인하세요:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">zsh --version</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_zsh를_기본_셸로_설정">Zsh를 기본 셸로 설정</h2> <div class="sectionbody"> <div class="paragraph"> <p>셸을 전역적으로 변경하거나 Kitty 내에서만 변경할 수 있습니다.</p> </div> <div class="sect2"> <h3 id="_전역_방법_모든_터미널에_대해">전역 방법 (모든 터미널에 대해)</h3> <div class="paragraph"> <p>절대 경로를 식별하세요 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">which zsh</code></pre> </div> </div> <div class="paragraph"> <p>일반적으로`/usr/bin/zsh`.</p> </div> <div class="paragraph"> <p>기본 셸을 변경하세요 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">chsh -s /usr/bin/zsh</code></pre> </div> </div> <div class="paragraph"> <p>로그아웃하고 다시 로그인하세요.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml title 전역 셸 변경 actor User User --> Bash : Session actuelle User --> System : chsh -s /usr/bin/zsh System --> "/etc/passwd" : Modifie le shell note right of "/etc/passwd" : Shell par défaut mis à jour @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_kitty_전용_방법">Kitty 전용 방법</h3> <div class="paragraph"> <p>Kitty에서 셸만 바꾸기를 원한다면, 구성 파일을 편집하세요:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">nano ~/.config/kitty/kitty.conf</code></pre> </div> </div> <div class="paragraph"> <p>이 줄을 추가하세요:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">shell zsh</code></pre> </div> </div> <div class="paragraph"> <p>저장하고 Kitty를 다시 시작하세요.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_zsh_구성_선택_사항">Zsh 구성 (선택 사항)</h2> <div class="sectionbody"> <div class="paragraph"> <p>Zsh를 사용자 지정하려면 :</p> </div> <div class="sect2"> <h3 id="_파일_zshrc_생성">파일 .zshrc 생성</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">touch ~/.zshrc nano ~/.zshrc</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_최소_구성_예시">최소 구성 예시</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">export ZSH_THEME="robbyrussell" export PATH="$HOME/.local/bin:$PATH" alias ll="ls -la"</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_완전한_워크플로_요약">완전한 워크플로 요약</h2> <div class="sectionbody"> <div class="paragraph"> <p>아래 다이어그램은 전체 프로세스를 요약합니다:</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml title 설치 및 구성 워크플로우 start :Téléchargement script Kitty; :Installation dans ~/.local; :Création symlink; :Ajout ~/.local/bin au PATH; if (Zsh installé ?) then (non) :sudo apt install zsh; endif :Configurer Kitty.desktop; :Optionnel - changer terminal par défaut; :Optionnel - chsh -s /usr/bin/zsh; stop @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_최종_검증">최종 검증</h2> <div class="sectionbody"> <div class="paragraph"> <p>키티 실행 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">kitty</code></pre> </div> </div> <div class="paragraph"> <p>당신은 그것을 보아야 합니다.`zsh`활성 상태입니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">echo $SHELL</code></pre> </div> </div> <div class="paragraph"> <p>예상 결과 :</p> </div> <div class="paragraph"> <p>/usr/bin/zsh</p> </div> <div class="paragraph"> <p>글꼴 크기를 변경하려면<strong>키티</strong>, 매개변수를 조정해야 합니다`font_size`구성 파일에서. 자세한 절차는 다음과 같습니다:</p> </div> <div class="sect2"> <h3 id="_구성_파일_열기">📂 구성 파일 열기</h3> <div class="paragraph"> <p>주요 구성 파일은 보통 다음 위치에 있습니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">~/.config/kitty/kitty.conf</code></pre> </div> </div> <div class="paragraph"> <p>이 파일이 아직 존재하지 않는 경우, 그것을 생성할 수 있습니다. 예시 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">nano ~/.config/kitty/kitty.conf</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_️_추가하거나_수정_font_size">🖋️ 추가하거나 수정 `font_size</h3> <div class="paragraph"> <p>다음 지시문을 추가하거나, 이미 존재한다면 수정하세요:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">font_size 14.0</code></pre> </div> </div> <div class="paragraph"> <p>여기`14.0`원하는 크기에 맞습니다. 원하는 소수 값을 입력할 수 있습니다, 예를 들어`12.0`, <code>15.5</code>, 등등</p> </div> </div> <div class="sect2"> <h3 id="_저장하고_kitty_다시_시작">💾 저장하고 Kitty 다시 시작</h3> <div class="ulist"> <ul> <li> <p>저장 (<code>Ctrl + O</code>, 그 다음에`Entrée`) 그리고 떠나세요 (<code>Ctrl + X</code>) 사용하신다면`nano`.</p> </li> <li> <p>Kitty의 모든 창을 닫은 다음, 변경 사항이 적용되도록 터미널을 다시 시작하세요.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_동적_조정_임시_줌">✅ 동적 조정 (임시 줌)</h3> <div class="paragraph"> <p>임시로 확대/축소하고 싶지만 설정을 변경하지 않으려면 기본 키보드 단축키를 사용하세요:</p> </div> <div class="ulist"> <ul> <li> <p><strong>글꼴 크기를 늘리다</strong>:</p> </li> </ul> </div> <div class="paragraph"> <p><code>Ctrl + Shift + =</code></p> </div> <div class="ulist"> <ul> <li> <p><strong>글꼴 크기 줄이기</strong>:</p> </li> </ul> </div> <div class="paragraph"> <p><code>Ctrl + Shift + -</code></p> </div> <div class="ulist"> <ul> <li> <p><strong>크기 재설정</strong>:</p> </li> </ul> </div> <div class="paragraph"> <p><code>Ctrl + Shift + Backspace</code></p> </div> <div class="paragraph"> <p>이 설정은 터미널을 닫은 후에도 유지되지 않습니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_oh_my_zsh_설치_및_구성">Oh My Zsh 설치 및 구성</h2> <div class="sectionbody"> <div class="paragraph"> <p>Zsh가 설치되고 기본 셸로 설정된 후, *Oh My Zsh*를 사용하여 환경을 풍부하게 할 수 있습니다. Zsh 구성을 관리하는 프레임워크인 *Oh My Zsh*는 다음과 같은 기능을 제공합니다:</p> </div> <div class="ulist"> <ul> <li> <p>프롬프트용 테마 컬렉션,</p> </li> <li> <p>많은 플러그인,</p> </li> <li> <p>구성의 명확한 조직.</p> </li> </ul> </div> <div class="sect2"> <h3 id="_oh_my_zsh_설치">Oh My Zsh 설치</h3> <div class="paragraph"> <p>Zsh가 활성화되어 있는지 확인하세요 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">zsh --version</code></pre> </div> </div> <div class="paragraph"> <p>필요하면 실행하세요:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">zsh</code></pre> </div> </div> <div class="paragraph"> <p>그런 다음 공식 설치 스크립트를 다운로드하고 실행하세요.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"</code></pre> </div> </div> <div class="paragraph"> <p>이 스크립트 :</p> </div> <div class="ulist"> <ul> <li> <p>폴더를 만들어`~/.oh-my-zsh`,</p> </li> <li> <p>가능하면 파일을 백업해 주세요`~/.zshrc`,</p> </li> <li> <p>새 프롬프트를 자동으로 활성화합니다.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_테마_변경">테마 변경</h3> <div class="paragraph"> <p>구성 파일을 엽니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">nano ~/.zshrc</code></pre> </div> </div> <div class="paragraph"> <p>변수를 수정하세요`ZSH_THEME`다른 테마를 선택하기 위해 (예를 들어`agnoster`) :</p> </div> <div class="paragraph"> <p>ZSH_THEME="agnoster</p> </div> <div class="paragraph"> <p>저장하고 구성을 다시 로드하세요:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">source ~/.zshrc</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_검증">검증</h3> <div class="paragraph"> <p>Kitty를 실행하고 프롬프트가 제대로 변경되었는지 확인하세요. 다음과 같이 실행하여 Oh My Zsh가 활성화되어 있는지 확인할 수 있습니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">echo $ZSH</code></pre> </div> </div> <div class="paragraph"> <p>결과가 비슷해야 합니다 :</p> </div> <div class="paragraph"> <p>/home/당신의_사용자/.oh-my-zsh</p> </div> </div> <div class="sect2"> <h3 id="_유스_케이스_다이어그램">유스 케이스 다이어그램</h3> <div class="listingblock"> <div class="content"> <pre>@startuml title 사용 사례 Oh My Zsh 설치 및 사용 actor Utilisateur as User package "키티 터미널" { component "Zsh 쉘" as Zsh } component "Oh My Zsh 프레임워크" as OhMyZsh User --> Kitty : Lance Kitty Kitty --> Zsh : Initialise Zsh Zsh --> OhMyZsh : Charge configuration (~/.zshrc, thèmes, plugins) User --> OhMyZsh : Personnalise le thème et les plugins @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_kitty에서_투명도_활성화">Kitty에서 투명도 활성화</h2> <div class="sectionbody"> <div class="paragraph"> <p>Kitty의 가장 좋아하는 기능 중 하나는 터미널 배경에 *투명도*를 추가할 수 있는 기능입니다. 이를 통해 창, 바탕화면 등 아래 환경을 약간 볼 수 있어 멀티태스킹 시 특히 유용합니다.</p> </div> <div class="sect2"> <h3 id="_투명성을_위한_사전_조건">투명성을 위한 사전 조건</h3> <div class="paragraph"> <p>키티의 투명성은 그것에 기반을 둔다<strong>윈도우 컴포지터</strong>그래픽 환경에서 사용됩니다. Xubuntu (XFCE 기반에서), …​인지 확인하세요<strong>구성이 활성화되었습니다.</strong>.</p> </div> <div class="ulist"> <div class="title">확인해야 할 :</div> <ul> <li> <p>바탕화면에서 오른쪽 클릭 > 설정 ><strong>창 관리자 설정</strong>,</p> </li> <li> <p>탭<strong>작곡가</strong>상자 : <strong>"컴포지션 활성화"</strong> 가 체크되어 있어야 합니다.</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre>@startuml title 사용 사례 - Kitty에서 투명도 활성화 actor Utilisateur rectangle "그래픽 환경 (XFCE/Xubuntu)" { usecase "구성 활성화" as UC1 } rectangle "고양이 터미널" { usecase "kitty.conf에서 투명도 설정" as UC2 } Utilisateur --> UC1 Utilisateur --> UC2 @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_kitty_conf에서_투명도_구성">kitty.conf에서 투명도 구성</h3> <div class="paragraph"> <p>설정 파일을 열어 주세요`~/.config/kitty/kitty.conf`(Empty output)</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">nano ~/.config/kitty/kitty.conf</code></pre> </div> </div> <div class="paragraph"> <p>다음 줄을 추가하거나 수정하세요 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-conf hljs" data-lang="conf">background_opacity 0.85</code></pre> </div> </div> <div class="paragraph"> <p>이 매개변수는 다음 사이의 값을 허용합니다:</p> </div> <div class="ulist"> <ul> <li> <p><code>1.0</code>→ 불투명 (투명도 없음),</p> </li> <li> <p><code>0.0</code>→ 완전히 투명한 (사용할 수 없는),</p> </li> <li> <p>중간 값과 같은`0.90`, <code>0.75</code>, 등등</p> </li> </ul> </div> <div class="paragraph"> <p>좋은 시각적 타협은 보통 사이에`0.85` et <code>0.95</code>.</p> </div> </div> <div class="sect2"> <h3 id="_kitty_재시작">Kitty 재시작</h3> <div class="paragraph"> <p>Kitty의 모든 인스턴스를 닫은 다음, 변경 사항이 적용되도록 새 창을 다시 시작하세요 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">kitty</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_가능한_보완">가능한 보완</h3> <div class="paragraph"> <p>사용자 지정 터미널 배경을 사용하고 있는 경우, RGBA를 사용한 투명 배경색도 설정할 수 있습니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-conf hljs" data-lang="conf">background #1e1e2eff</code></pre> </div> </div> <div class="paragraph"> <p>마지막 구성 요소 (<code>ff</code>) indique l’opacité (de`00` à <code>ff</code>).</p> </div> </div> <div class="sect2"> <h3 id="_시퀀스_다이어그램_kitty_투명도_초기화">시퀀스 다이어그램 - Kitty 투명도 초기화</h3> <div class="listingblock"> <div class="content"> <pre>@startuml title 투명성을 갖춘 Kitty 시작 시퀀스 actor User participant "키티" as Kitty participant "XFCE 작곡가" as XFCE participant "GPU/윈도우 관리자" as WM User -> Kitty : Lance Kitty Kitty -> kitty.conf : Lit configuration Kitty -> XFCE : Vérifie composition activée XFCE --> Kitty : Composition = active Kitty -> WM : Demande allocation fenêtrée transparente WM --> Kitty : OK (rendu avec alpha < 1) Kitty -> User : Affiche terminal translucide @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_알려진_제한">알려진 제한</h3> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td> <td class="content"> <div class="paragraph"> <p>투명도가 작동하지 않을 경우: - XFCE 컴포지터가 비활성화됨, - 호환되지 않는 윈도우 관리자가 사용되고 있습니다, - 당신은 Kitty를 <strong>tmux</strong> 모드에서 배경에서 사용하고 있으며 투명도 지원이 없습니다.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_벨_소리_비활성화_청각적_벨">벨 소리 비활성화 (청각적 벨)</h2> <div class="sectionbody"> <div class="paragraph"> <p>기본적으로 Kitty는 <strong>bip</strong> 소리를 내며, 잘못된 명령이 입력되거나 터미널 이벤트가 이를 트리거할 때 발생합니다. 이 소음은 특히 강도 높은 개발 환경에서는 빠르게 성가신 것이 될 수 있습니다.</p> </div> <div class="paragraph"> <p>이 동작을 비활성화하려면 파일에 다음 지시문을 추가`~/.config/kitty/kitty.conf`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-conf hljs" data-lang="conf">audible_bell no</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>또한 *시각 피드백*을 소리 대신 활성화할 수 있습니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-conf hljs" data-lang="conf">visual_bell yes</code></pre> </div> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_kitty_업데이트">Kitty 업데이트</h2> <div class="sectionbody"> <div class="paragraph"> <p>Kitty가 스크립트를 통해 설치되었고 패키지 관리자가 아니기 때문에, 업데이트는 공식 설치 스크립트를 다시 실행하여 수행됩니다. 이를 통해 최신 버전을 다운로드하고 기존 설치를 업데이트할 수 있습니다 안에`~/.local/kitty.app`.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>접미사`.app`길에서`~/.local/kitty.app`Kitty의 Linux 설치 방식은 공식 스크립트를 통해 이루어지며, 이는 macOS와의 독점적 호환성을 나타내는 것이 아닙니다.</p> </div> </td> </tr> </table> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="Important"></i> </td> <td class="content"> <div class="paragraph"> <p>업데이트 명령을 실행하기 전에, 개인 디렉터리에 있는지 확인하세요 (<code>~</code>).</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>다음 명령을 홈 디렉터리에서 실행하세요:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh /dev/stdin</code></pre> </div> </div> <div class="paragraph"> <p>이 스크립트는 다음을 담당할 것입니다 :</p> </div> <div class="ulist"> <ul> <li> <p>새 버전의 바이너리를 다운로드하다</p> </li> <li> <p>파일을 추출하여`~/.local/kitty.app`.</p> </li> <li> <p>필요한 경우 심볼릭 링크를 업데이트하세요.</p> </li> </ul> </div> <div class="paragraph"> <p>업데이트 후, Kitty의 모든 인스턴스를 종료하고 다시 시작하여 새로운 버전이 제대로 적용되도록 하는 것이 권장됩니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_참고문헌">참고문헌</h2> <div class="sectionbody"> <div class="paragraph"> <p>개인화를 더 깊이 있게 탐구하고 싶다면 공식 문서를 참조하세요:</p> </div> <div class="ulist"> <ul> <li> <p>키티 : <a href="https://sw.kovidgoyal.net/kitty/" class="bare">https://sw.kovidgoyal.net/kitty/</a></p> </li> <li> <p><a href="https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.background_opacity" class="bare">https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.background_opacity</a></p> </li> <li> <p><a href="https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.audible_bell" class="bare">https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.audible_bell</a></p> </li> <li> <p>Zsh : <a href="https://zsh.sourceforge.io/" class="bare">https://zsh.sourceforge.io/</a></p> </li> <li> <p>깃허브: <a href="https://github.com/kovidgoyal/kitty" class="bare">https://github.com/kovidgoyal/kitty</a></p> </li> <li> <p>Zsh: <a href="https://zsh.sourceforge.io/" class="bare">https://zsh.sourceforge.io/</a></p> </li> <li> <p><a href="https://ohmyz.sh/" class="bare">https://ohmyz.sh/</a></p> </li> <li> <p><a href="https://github.com/ohmyzsh/ohmyzsh/wiki" class="bare">https://github.com/ohmyzsh/ohmyzsh/wiki</a></p> </li> <li> <p><a href="https://docs.xfce.org/xfce/xfwm4/compositor" class="bare">https://docs.xfce.org/xfce/xfwm4/compositor</a></p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_결론">결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>이제 다음과 같습니다:</p> </div> <div class="ulist"> <ul> <li> <p>(Kitty)의 현대적이며 성능이 좋은 터미널</p> </li> <li> <p>강력하고 사용자 지정 가능한 셸 (Zsh)의</p> </li> <li> <p>시스템 패키지와 독립적인 깨끗한 구성</p> </li> <li> <p>아름다우면서도 기능적인 Oh My Zsh가 장착된 터미널의</p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0119_benchmark_dgx_spark_vs_cloud_abonnement_llm_post.html Wed, 6 May 2026 00:00:00 +0000 blog/2026/0119_benchmark_dgx_spark_vs_cloud_abonnement_llm_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_컨텍스트_변동된_시장">컨텍스트 : 변동된 시장</a></li> <li><a href="#_옵션_패널">옵션 패널</a> <ul class="sectlevel2"> <li><a href="#_제가_제외시킨_것_그리고_왜">제가 제외시킨 것 (그리고 왜)</a></li> </ul> </li> <li><a href="#_간단한_추론_로컬_하드웨어의_죽음">간단한 추론 : 로컬 하드웨어의 죽음</a> <ul class="sectlevel2"> <li><a href="#_계산">계산</a></li> <li><a href="#_집중적인_사용을_하더라도">집중적인 사용을 하더라도</a></li> </ul> </li> <li><a href="#_파인튜닝_클라우드는_절대_지지_않는다">파인튜닝: 클라우드는 절대 지지 않는다</a> <ul class="sectlevel2"> <li><a href="#_fine_tune의_실제_비용">Fine-Tune의 실제 비용</a></li> <li><a href="#_특수_배우">특수 배우</a></li> </ul> </li> <li><a href="#_유일한_진짜_이유_데이터_주권">유일한 진짜 이유: 데이터 주권</a> <ul class="sectlevel2"> <li><a href="#_진정한_프라이버시_계산">진정한 프라이버시 계산</a></li> </ul> </li> <li><a href="#_요약_결정_매트릭스">요약: 결정 매트릭스</a></li> <li><a href="#_특별_사례_중국_모델에_맞서는_프로_구독">특별 사례: 중국 모델에 맞서는 프로 구독</a> <ul class="sectlevel2"> <li><a href="#_왜_중국_모델들이_모든_것을_바꾼다">왜 중국 모델들이 모든 것을 바꾼다?</a></li> <li><a href="#_하드웨어를_위한_의미">하드웨어를 위한 의미</a></li> </ul> </li> <li><a href="#_그리고_화웨이">그리고 화웨이?</a></li> <li><a href="#_결론_근접의_럭셔리">결론: 근접의 럭셔리</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽는 시간 : 14 minutes</div> <p>NVIDIA는 DGX Spark를 '데스크톱 AI 슈퍼컴퓨터’로 $4,699에 판매합니다. Ollama는 클라우드 모델을 $20/월에 제공합니다. Vast.ai에서 H100은 $1.38/시간에 대여할 수 있습니다. 그리고 중국 오픈소스 모델인 DeepSeek, Qwen, GLM은 어디서든 무료로 이용 가능하며, 카드를 구매할 필요가 없습니다. 그렇다면 이 Spark는 정확히 어떤 용도로 사용됩니까? 저는 계산을 해봤습니다.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">틱</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_컨텍스트_변동된_시장">컨텍스트 : 변동된 시장</h2> <div class="sectionbody"> <div class="paragraph"> <p>2026년 5월, 인공지능 환경은 2025년 CES에서 발표된 DGX Spark 발표와 비교해 근본적으로 바뀌었습니다. 세 가지 힘이 모여 로컬 하드웨어를 점점 더 정당화하기 어렵게 만들었습니다:</p> </div> <div class="ulist"> <ul> <li> <p><strong>클라우드 GPU 가격 폭락</strong>H100은 시간당 $1.38에서 $3 사이로 대여되며, 18개월 전에는 시간당 $5~$8이었습니다.</p> </li> <li> <p><strong>중국 오픈소스 모델의 폭발</strong>: DeepSeek-V4, Qwen-3, GLM-5는 서구 모델과 경쟁력이 있으며 무료로 이용 가능합니다.</p> </li> <li> <p><strong>관리형 추론 플랫폼의 부상</strong>Ollama, Groq, Together AI는 공격적인 가격의 API를 제공하며, 관대한 무료 티어도 제공합니다.</p> </li> </ul> </div> <div class="paragraph"> <p>$2,999에 발표된 후 $4,699로 인상된 DGX Spark는 더 이상 필요하지 않은 세상에 도착한다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_옵션_패널">옵션 패널</h2> <div class="sectionbody"> <div class="paragraph"> <p>2026년 5월에 이용 가능한 LLM을 실행하는 솔루션, 가장 가벼운 것부터 가장 무거운 것까지:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">옵션</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">비용</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">VRAM / 용량</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">접근 가능한 모델</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">주요 제약</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ollama 무료</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$0/월</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">경량 클라우드</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">모든 공개 모델</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">제한된 사용, 동시에 1개 모델</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>클로드 프로</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$20/월 (~$240/년)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N/A (API 닫힘)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Claude 4.x만</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">유일한 모델, 오픈소스가 아님</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ollama Pro</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$20/월 (~$200/년)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">클라우드 매체</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">모든 공개 모델</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">최대 3개의 동시 모델</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ollama Max</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$100/월 (~$1 200/년)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">클라우드 무거운</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">모든 공개 모델</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">10개 동시 모델</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>클라우드 GPU (H100)</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$1.38-3/h</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">80 Go HBM</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">모든 모델, 파인튜닝</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">시간당 청구, 설정 필요</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>DGX Spark</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$4 699 (구매)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">128 Go unifié</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tous modèles <128 Go</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">느림(~10배 더 낮음, H100 대비), 고정</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>맥 스튜디오 M3 울트라</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~$5 000+</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">192 Go unifié</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tous modèles <192 Go</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">CUDA가 아님, MLX 생태계</p></td> </tr> </tbody> </table> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>인용된 클라우드 GPU 가격은 2026년 5월에 Vast.ai와 RunPod의 가격이다 — 스팟/온디맨드 가격이며, 예약 가격이 없습니다.</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_제가_제외시킨_것_그리고_왜">제가 제외시킨 것 (그리고 왜)</h3> <div class="paragraph"> <p>나는 다음과 같은 옵션들을 이 벤치마크에서 의도적으로 제외했습니다:</p> </div> <div class="ulist"> <ul> <li> <p><strong>에이피아이 오픈AI / 앤스로픽 / 구글</strong>여기서 주제는 선택할 수 있고, fine-tuning 할 수 있으며, 단일 벤더에 의존하지 않는 오픈소스 모델을 실행하는 것입니다.</p> </li> <li> <p><strong>Huawei Ascend / Atlas</strong> : Huawei ne commercialise pas d’équivalent desktop au DGX Spark. La gamme Ascend (910C, 910D) et Atlas (300I Duo, 350) est orientée datacenter — cartes PCIe, serveurs rack — pas des boîtiers compacts prêts à brancher. La puce Ascend 910C embarque 128 Go HBM mais c’est une puce serveur, pas un système autonome. L’Atlas 300I Duo offre 96 Go pour ~$1 400 mais nécessite une machine hôte</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_간단한_추론_로컬_하드웨어의_죽음">간단한 추론 : 로컬 하드웨어의 죽음</h2> <div class="sectionbody"> <div class="paragraph"> <p>가장 일반적인 사용 사례부터 시작해 보겠습니다: LLM과 채팅하기, 코드 리뷰하기, 텍스트 생성하기. 파인튜닝도 배치 처리도 없이, 단지 대화형 추론만 수행합니다.</p> </div> <div class="sect2"> <h3 id="_계산">계산</h3> <div class="paragraph"> <p>DGX Spark는 $4,699. 각 구독의 연간 비용으로 나누어 봅시다:</p> </div> <div id="diag-breakeven" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title 손익분기점 — DGX Spark ($4 699) vs 구독 rectangle "DGX Spark $4 699" as spark #FFCDD2 rectangle "Ollama Pro $200/년" as opro #C8E6C9 rectangle "Claude Pro $240/년" as cpro #C8E6C9 rectangle "Ollama Max $1 200/년" as omax #FFF9C4 rectangle "Cloud H100 시간당 $3 × 주당 10시간" as cloud #BBDEFB spark --> opro : 23.5 années ⏳ spark --> cpro : 19.6 années ⏳ spark --> omax : 3.9 années spark --> cloud : 3.0 années (à 10h/semaine, intermittent) note bottom of spark Sans compter l'électricité (~$150/an) Sans compter l'obsolescence hardware Sans compter qu'il est 10x plus lent end note @enduml</pre> </div> </div> <div class="paragraph"> <p>판결은 잔혹합니다. 추론을 위해:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Ollama Pro</strong>당신이 필요하실 겁니다<strong>23세</strong>DGX Spark를 상각하기 위해. Spark는 20년 후에는 낡은 기술이 될 것입니다.</p> </li> <li> <p><strong>Ollama Max</strong> : <strong>4년</strong>— Spark 24/7을 사용하는 것을 조건으로, 아무도 하지 않는 일</p> </li> <li> <p><strong>클로드 프로</strong>: 같은 문제,<strong>20년</strong>폐쇄된 단일 모델용</p> </li> </ul> </div> <div class="paragraph"> <p><em><em>_ 데스크톱용 AI 슈퍼컴퓨터의 약속은 기초적인 회계 현실과 충돌합니다: $4 699 / $20/월 = 개인 사용으로는 절대 수익이 나지 않습니다. </em>_</em></p> </div> </div> <div class="sect2"> <h3 id="_집중적인_사용을_하더라도">집중적인 사용을 하더라도</h3> <div class="paragraph"> <p>클라우드 최악의 시나리오: 하루 8시간, 주 5일, 연간 52주 동안 H100을 가동합니다.</p> </div> <div class="ulist"> <ul> <li> <p>8 × 5 × 52 = 2 080 시간/년</p> </li> <li> <p>2 080 × $2/h (H100 스팟 평균 가격) =<strong>$4 160/년</strong></p> </li> </ul> </div> <div class="paragraph"> <p>스파크($4 699)는 …​에서 회수됩니다<strong>13개월</strong>. 그런데 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>H100은<strong>~10x 더 빠르다</strong>GB10의 Spark와 비교하면, 1시간에 Spark가 10시간 하는 일을 해냅니다. 동일한 작업량 기준으로 H100은 연간 $416 정도 비용이 듭니다, $4,160이 아닙니다.</p> </li> <li> <p>Le H100 a 80 Go HBM à 3.35 To/s de bande passante. Le Spark a 128 Go LPDDR5X à 273 Go/s. Pour les gros modèles, la bande passante compte plus que la capacité.</p> </li> </ol> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>H100 1시간과 Spark 1시간을 비교하는 것은 의미가 없습니다. H100은 작업을 10배 더 빨리 수행합니다. 따라서 특정 워크로드에 대한 실제 클라우드 비용은 시간 기반 순수 계산보다 약 10배 낮습니다.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_파인튜닝_클라우드는_절대_지지_않는다">파인튜닝: 클라우드는 절대 지지 않는다</h2> <div class="sectionbody"> <div class="paragraph"> <p>스파크 옹호자들의 전통적인 주장 : « 예, 그러나 파인튜닝에 대해서는 다릅니다.</p> </div> <div class="paragraph"> <p>아니요, 그렇지 않아요.</p> </div> <div class="sect2"> <h3 id="_fine_tune의_실제_비용">Fine-Tune의 실제 비용</h3> <div class="paragraph"> <p>Unsloth에서 7B 모델에 대한 LoRA/QLoRA 파인튜닝 :</p> </div> <div class="ulist"> <ul> <li> <p>~2-3h H100에서 =<strong>$5에서 $9까지</strong></p> </li> <li> <p>스파크에서도 똑같다 =<strong>20-30시</strong>(10배 느리게), 기계를 정지시킵니다</p> </li> </ul> </div> <div class="paragraph"> <p>Spark의 $4,699로 다음을 자금 조달할 수 있습니다 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>~500에서 ~900개의 fine-tunes</strong>클라우드 H100에서</p> </li> <li> <p>Ou <strong>약 23세</strong>Ollama Pro</p> </li> <li> <p>Ou <strong>~4년</strong>ollama 맥스</p> </li> </ul> </div> <div class="paragraph"> <p>그리고 더 큰 모델(70B+):</p> </div> <div class="ulist"> <ul> <li> <p>Le Spark avec ses 128 Go peut charger un 70B en Q4 — mais le fine-tune sera extrêmement lent</p> </li> <li> <p>Un H100 avec 80 Go peut fine-tuner un 70B en QLoRA 4-bit en quelques heures</p> </li> <li> <p>풀 파인튜닝을 위해서는 어쨌든 멀티 GPU가 필요합니다 — 스파크는 경쟁에서 벗어났습니다.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_특수_배우">특수 배우</h3> <div class="paragraph"> <p>2026년에, Unsloth, Modal, Replicate, Together AI와 같은 플랫폼은 서버리스 파인튜닝을 제공합니다:</p> </div> <div class="ulist"> <ul> <li> <p>GPU 관리가 없습니다</p> </li> <li> <p>환경 구성이 없습니다</p> </li> <li> <p>분당 결제</p> </li> <li> <p>통합 최적화 (flash attention, 자동 양자화)</p> </li> </ul> </div> <div id="diag-fine-tuning-cost" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title <size:20>LoRA 7B 파인튜닝 비용 — 비교</size> note as N |= Option |= Coût par fine-tune |= Fine-tunes possibles avec $4 699 | | **Replicate** | $3-5 | ~1 000 | | **Modal (serverless)** | $2-4 | ~1 500 | | **Unsloth + Vast.ai H100** | $5-9 | ~500-900 | | **Together AI** | $4-8 | ~600-1 000 | | **DGX Spark** | « gratuit » mais 20-30h | ∞ (en théorie) | end note note bottom Le Spark est « gratuit » par fine-tune seulement si votre temps vaut $0/h et que vous n'avez pas besoin de la machine pour autre chose pendant 30h end note @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_유일한_진짜_이유_데이터_주권">유일한 진짜 이유: 데이터 주권</h2> <div class="sectionbody"> <div class="paragraph"> <p>추론, 파인튜닝, 비용 대비 성능을 모두 제거한 후 Spark에 남은 것은 무엇입니까?</p> </div> <div class="paragraph"> <p><strong>절대적인 기밀.</strong></p> </div> <div class="paragraph"> <p>비밀유지 문제라기보다는 — “내 프롬프트가 OpenAI 직원에 의해 읽히길 원하지 않는다” — 이것은 2026년에 잘못된 우려입니다: Ollama, Groq 및 대부분의 신뢰할 수 있는 서비스 제공업체는 무로그 및 무보존 정책을 가지고 있습니다.</p> </div> <div class="paragraph"> <p>진정한 기밀성, 그것은 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>규제 에어 갭</strong>défense, diplomatie, santé — les données ne peuvent <strong>physiquement</strong> pas quitter le bâtiment</p> </li> <li> <p><strong>중요한 사유 데이터</strong>: 미공개 제품의 소스 코드, 산업 비밀, 거래 알고리즘</p> </li> <li> <p><strong>네트워크 복원력</strong>: AI는 인터넷이 끊어져도 계속 작동해야 한다</p> </li> </ul> </div> <div class="admonitionblock caution"> <table> <tr> <td class="icon"> <i class="fa icon-caution" title="🔒"></i> </td> <td class="content"> <div class="paragraph"> <p>하지만 솔직히 말하자면 : DGX Spark 구매자 중 실제로 해당되는 비율이 몇 퍼센트인가? 1%인가? 나머지는 단순히 « nice to have »가 $4,699 지출로 바뀐 것이다.</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_진정한_프라이버시_계산">진정한 프라이버시 계산</h3> <div class="paragraph"> <p>개인용 사용 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>올라마 프로</strong>$20/월 + 중국 오픈소스 모델 = 실용적 솔루션</p> </li> <li> <p>Ollama에서 프롬프트가 유출되면 매일 수백만 건의 요청 속에서 사라집니다. 이것은 바다 속의 한 방울 물과 같습니다.</p> </li> <li> <p>실제 위험은 프롬프트 유출이 아니라 — 귀하의 데이터에 대한 비동의적 훈련입니다. 그리고 그것에 대해, 진지한 제공업체들은 계약적으로 이를 금지합니다.</p> </li> </ul> </div> <div class="paragraph"> <p><em><em>_ distiller son prompt dans le LLM »에 대한 두려움은 개인적인 정보 전파 수준이 너무 희석되어 실제 위협보다는 불안에 가깝다. 산업 규모에서는 다르지만, 개인 수준에서는 단지 소음이다. </em>_</em></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_요약_결정_매트릭스">요약: 결정 매트릭스</h2> <div class="sectionbody"> <div id="diag-decision-matrix" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title 2026년에 어떤 AI 솔루션을 선택해야 할까요? start :Quel est votre besoin principal ?; switch (Besoin) case (Inférence interactive occasionnelle) :**Ollama Free**\n$0/mois, tous modèles open-source; stop case (Inférence quotidienne, code review, dev) :**Ollama Pro** ($20/mois)\nAccès à tous les modèles open-source\nDeepSeek, Qwen, GLM, Llama, Mistral; stop case (Agents IA, multi-modèles, usage intensif) :Contexte > 30K tokens ?; if (Oui) then :**Ollama Max** ($100/mois)\n10 modèles simultanés\nContexte long sans dégradation; stop else (Non) :**Cloud GPU H100 spot** ($1.38–3/h)\n+ Unsloth/Modal pour fine-tuning\nPerformance brute maximale; stop endif case (Fine-tuning régulier) :**Vast.ai H100 + Unsloth** ($5–9/fine-tune)\nou **Together AI / Modal** (serverless)\n500+ fine-tunes pour le prix d’un Spark; stop case (Air-gap obligatoire) :Données classifiées ?; if (Oui) then :**DGX Spark** ou **Mac Studio M3 Ultra**\nSeul cas où le hardware local est justifié\n(pas économiquement — politiquement); stop else (Non) :Retour au cloud : pas de besoin d’air-gap; stop endif endswitch @enduml</pre> </div> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2232%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">기준</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ollama 무료</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ollama Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">클라우드 GPU H100</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DGX Spark</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>추론</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ 제한된</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ 편안한</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ 과잉</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">느린</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>세밀한 조정</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ 무적</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">⚠️ 가능하지만 느립니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>연간 비용</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$200</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">변수 (~$416-2 080*)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$4 699 선불</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>기밀성</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">⚠️ 클라우드 미국</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">⚠️ 클라우드 미국</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">⚠️ Cloud US (변수)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ 전체</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>유지보수</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">아무것도</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">없음</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">고유한 설정</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">전기, 업데이트</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>노후화</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">없음</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">없다</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">없다</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3-5년</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>소프트웨어 생태계</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">모든 모델이 열려 있습니다</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">모든 모델 오픈</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">모든 모델 오픈</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">CUDA(지만 느림)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>평결</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">가끔</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>추천된</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">장점/연구</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">에어 갭만</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><em>*작업량에 따라 변하는 변수 ; H100 속도 ~10x > Spark, 주어진 워크로드에 대한 실제 비용은 낮다.</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_특별_사례_중국_모델에_맞서는_프로_구독">특별 사례: 중국 모델에 맞서는 프로 구독</h2> <div class="sectionbody"> <div class="paragraph"> <p>하나의 점을 강조해야 합니다: 결합<strong>Ollama Pro $20/월 + 중국 오픈소스 모델</strong>이는おそらく 소비자 AI 역사상 최고의 가성비를 가지고 있다.</p> </div> <div class="sect2"> <h3 id="_왜_중국_모델들이_모든_것을_바꾼다">왜 중국 모델들이 모든 것을 바꾼다?</h3> <div class="ulist"> <ul> <li> <p><strong>DeepSeek-V4-Pro</strong>: 1.6T 파라미터, CSA+HCA, 1M 컨텍스트, Claude 4 및 GPT-5와 코드 측면에서 경쟁력 있음</p> </li> <li> <p><strong>Qwen-3</strong>: 235B, 256K 컨텍스트, 프랑스어와 추론에서 뛰어남</p> </li> <li> <p><strong>GLM-5.1</strong>: 744B, MLA+DSA, 200K 컨텍스트, 에이전틱에 최적화된</p> </li> </ul> </div> <div class="paragraph"> <p>모두 Ollama에서 이용할 수 있습니다. 모두 오픈소스(허가형 라이선스)이며, $20/월 구독을 통해 제한 없이 이용할 수 있습니다.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>Ollama Pro를 사용하면 닫힌 모델 하나(예: Claude Pro)의 가격으로 오픈 소스 'frontier' 모델 ~5개에 접근할 수 있습니다. 그 가치가 너무 비대칭적이어서 거의 터무니없다.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_하드웨어를_위한_의미">하드웨어를 위한 의미</h3> <div class="paragraph"> <p>최고의 가격 대비 성능이 월 $20인 클라우드 구독이라면, 로컬 하드웨어는 <strong>편안함</strong> 또는 *원칙*을 위한 선택이 되며 — 경제적인 선택은 아니다.</p> </div> <div class="paragraph"> <p>4,699달러의 DGX Spark는 다음과 같습니다:</p> </div> <div class="ulist"> <ul> <li> <p>235개월 Ollama Pro</p> </li> <li> <p>23개의 AAA 게임 출시일</p> </li> <li> <p>4 MacBook Air M4</p> </li> <li> <p>리용의 T2 아파트 1년치 임대료</p> </li> </ul> </div> <div class="paragraph"> <p>계산을 위해. 느리게</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_그리고_화웨이">그리고 화웨이?</h2> <div class="sectionbody"> <div class="paragraph"> <p>질문이 연구 중에 제기되었기 때문에: 아닙니다, Huawei는 DGX Spark에 상응하는 제품을 판매하지 않습니다.</p> </div> <div class="paragraph"> <p>존재하는 것 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Ascend 910C</strong> : 128 Go HBM, 800 TFLOPS FP16 — mais c’est une puce serveur, pas un desktop</p> </li> <li> <p><strong>Atlas 300I Duo</strong> : 96 Go LPDDR4X, carte PCIe à ~$1 400 — nécessite un hôte</p> </li> <li> <p><strong>아틀라스 350</strong> : 112 Go HBM, 1.56 PFLOPS FP4 — accélérateur datacenter, pas un boîtier compact</p> </li> </ul> </div> <div class="paragraph"> <p>Huawei reste focalisé sur le marché des serveurs et des centres de données. Pour un boîtier compact « prêt à brancher » avec 120+ Go de VRAM, le DGX Spark (128 Go unifié) et le Mac Studio M3 Ultra (192 Go unifié) sont les seules options en 2026. Et pour l’instant, aucun constructeur chinois n’a annoncé de produit équivalent dans ce format.</p> </div> </div> </div> <div class="sect1"> <h2 id="_결론_근접의_럭셔리">결론: 근접의 럭셔리</h2> <div class="sectionbody"> <div class="paragraph"> <p>DGX Spark은 나쁜 제품이 아닙니다. 이는 잠재 구매자 99%에게 나쁜 투자입니다.</p> </div> <div id="diag-verdict" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title 2026년 AI 풍경 — 누가 지배하고 있나요? left to right direction package "개인 사용 / 중소기업" #C8E6C9 { rectangle "🏆 Ollama Pro $20/월" as pro rectangle "Ollama Free $0/월" as free rectangle "클라우드 GPU 스팟 $1-3/h" as spot } package "집중 사용 / 프로" #FFF9C4 { rectangle "🏆 Ollama Max $100/월" as max rectangle "🏆 전용 클라우드 GPU $2-4/h" as dedicated rectangle "Modal / Together AI\n서버리스" as serverless } package "필수 에어 갭" #FFCDD2 { rectangle "DGX Spark $4 699" as spark rectangle "Mac Studio M3U 약 $5,000" as mac } note bottom of spark 1% des cas d'usage — défense, santé réglementée, secrets industriels critiques end note @enduml</pre> </div> </div> <div class="paragraph"> <p><em><em>_ 2026년에 DGX Spark를 구매하는 것은 2010년에 메일 서버를 구매하는 것과 같다: 기술적으로는 가능하고, 철학적으로는 만족스럽지만, 경제적으로는 개인에게 비합리적이다. </em>_</em></p> </div> <div class="paragraph"> <p>계산은 간단하고, 그것은 거짓말을 하지 않아요 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>$0</strong>Ollama Free에서 DeepSeek과 채팅하기</p> </li> <li> <p><strong>$200/년</strong>Ollama Pro와 진지하게 일하기 위해</p> </li> <li> <p><strong>$5-9</strong>클라우드 GPU에서의 일시적 파인튜닝을 위해</p> </li> <li> <p><strong>$4 699</strong>…​ NVIDIA 케이스를 책상 위에 두고 느껴보는 경험은?</p> </li> </ul> </div> <div class="paragraph"> <p>시장이 결정했다. 클라우드 구독과 중국의 오픈소스 모델이 가격 경쟁에서 승리했다. 현지 하드웨어는 규제 니치에서 살아남으며, 개발자 사무실에서는 그렇지 않다.</p> </div> <div class="paragraph"> <p><em><em>_ DGX Spark는 수익성이 좋은 도구가 아닙니다. 그것은 선언입니다. “나는 나만의 AI를 집에서 원하고, 남의 클라우드는 원하지 않아.” 그건 존중할 만합니다. 하지만 2026년, Ollama가 클라우드에서 DeepSeek-V4-Pro를 월 $20에 제공할 때, 그것은 주로 매우 비싼 선언입니다. </em>_</em></p> </div> <hr> <div class="paragraph"> <p><strong>이 글은 DGX Spark의 경제적 타당성에 관한 나의 AI 에이전트와의 대화에서 비롯되었으며, 클라우드 GPU 가격(Vast.ai, RunPod) 시장 모니터링, Ollama/Claude 가격표, 그리고 중국 오픈소스 모델 생태계와 결합되었습니다. 인용된 가격은 2026년 5월의 것이며, 이 글을 읽으실 때는 아마도 아직 더 낮아졌을 것입니다.</strong></p> </div> </div> </div> https://cheroliv.com/blog/2026/0118_matrice_gouvernance_llm_zone_acces_workspace_post.html Mon, 4 May 2026 00:00:00 +0000 blog/2026/0118_matrice_gouvernance_llm_zone_acces_workspace_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_문제_프롬프트_엔지니어링은_모래성이다">문제: 프롬프트 엔지니어링은 모래성이다</a></li> <li><a href="#_내_답변_44_행렬">내 답변: 4×4 행렬</a> <ul class="sectlevel2"> <li><a href="#_다섯_개_구역_공간_차원_rgpd">다섯 개 구역 (공간 차원 — RGPD)</a></li> <li><a href="#_인식론적_분류_두_번째_차원">인식론적 분류 (두 번째 차원)</a></li> </ul> </li> <li><a href="#_llm이_이_행렬을_어떻게_소비하는가">LLM이 이 행렬을 어떻게 소비하는가</a></li> <li><a href="#_구현_타입이_지정된_gradle_작업">구현 : 타입이 지정된 Gradle 작업</a></li> <li><a href="#_왜_이것이_선언문이지_단순한_사양이_아닌가">왜 이것이 선언문이지, 단순한 사양이 아닌가?</a></li> <li><a href="#_완전한_폭포_brain_dump에서_블로그_글까지">완전한 폭포 — Brain Dump에서 블로그 글까지</a></li> <li><a href="#_찬성반대">찬성/반대</a></li> <li><a href="#_결론_파일을_정리하고_프롬프트를_정리하지_마세요">결론: 파일을 정리하고, 프롬프트를 정리하지 마세요.</a></li> <li><a href="#_참고문헌">참고문헌</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽기 시간 : 14 minutes</div> <p>몇 달 동안 나는 에이전트 거버넌스 규칙을 쌓아 올렸다. 파일들 EAGER, LAZY 체크리스트, 여섯 단계 세션 종료 프로토콜. 그리고, 여전히 해결되지 않은 질문이 하나 남아 있었다: <strong>comment le LLM sait-il ce qu’il 파일에 대해 할 권리가 있다 ?</strong></p> </div> <div class="paragraph"> <p>답은 프롬프트에 있지 않습니다. 파일 시스템에 있습니다.</p> </div> <div class="paragraph"> <p>다음은 응답을 이용할 수 있게 하는 아키텍처 사양입니다 — la <strong>LLM 거버넌스 매트릭스</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_문제_프롬프트_엔지니어링은_모래성이다">문제: 프롬프트 엔지니어링은 모래성이다</h2> <div class="sectionbody"> <div class="paragraph"> <p>LLM에 파일을 주면 그 모든 것을 주는 것 같아요. 내용이죠 — 그리고 보호 장치의 부재도 있다. LLM은 이 파일이 포함하고 있는지 모른다. 비밀, 추측적인 의견, 또는 폐쇄형 소스 코드. 그는 그것을 색인화할 것, 요약하고, 인용하고, 다른 데이터와 섞는 것 — 그리고 잠재적으로 공개 임베딩 또는 사용자 응답에 게시하다.</p> </div> <div class="paragraph"> <p>고전적인 퍼레이드, 그것은 프롬프트:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">"Tu es un assistant sécurisé. Ne divulgue jamais d'informations confidentielles. Si tu détectes un secret, ignore-le. Si tu détectes une opinion, ne la répète pas."</code></pre> </div> </div> <div class="paragraph"> <p>이 프롬프트에는 세 가지 문제가 있습니다.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>LLM의 선의에 의존합니다.</strong> 충분히 큰 모델은</p> </li> </ol> </div> <div class="paragraph"> <p>복잡한 버그를 해결하는 것은 충분히 커서 명령어를 우회할 수 있다 보안의 200k 토큰의 맥락 속에 잠긴</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>이것은 문맥적이며 구조적이지 않다.</strong> 프롬프트를 바꾸고, LLM을 바꾸라,</p> </li> </ol> </div> <div class="paragraph"> <p>세션을 바꾸면 — 규칙이 사라집니다.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>확장되지 않습니다.</strong> 각 새로운 파일 유형, 각 새로운 레벨</p> </li> </ol> </div> <div class="paragraph"> <p>개인정보 보호는 새로운 조항이 필요합니다. 당신의 프롬프트는 아무도 다 읽지 않는 규정 텍스트</p> </div> <div class="admonitionblock caution"> <table> <tr> <td class="icon"> <i class="fa icon-caution" title="🔒"></i> </td> <td class="content"> <div class="paragraph"> <p>시스템의 보안은 절대 우리가 하는 명령에 의존해서는 안 된다 잊을 수도, 우회하거나 로드하지 않을 수도 있습니다. 그녀는 하나의 것에 의존해야 합니다. 명시적으로 원하지 않는 한 넘을 수 없는 장벽.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_내_답변_44_행렬">내 답변: 4×4 행렬</h2> <div class="sectionbody"> <div class="paragraph"> <p>내가 워크스페이스에서 구현한 솔루션은 <strong>영역 행렬 × LLM</strong>. 그녀는 LLM에게 주의하도록 요구하지 않는다. 그녀는 구조적으로 불가능한 무모함.</p> </div> <div id="diag-matrix-overview" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 220 title LLM 거버넌스 매트릭스 — 영역 × 접근 권한 package "작업 공간" { rectangle "RACINE (원 0) ━━━━━━ 뇌 덤프 자유로운 생각 [LLM 사용 금지]" as Z0 #FFB3B3 rectangle "configuration/ (원 1) ━━━━━━ 비밀, 토큰 프라이빗 인프라 [금지 LLM]" as Z1 #FFB3B3 rectangle "office/ (원 2) ━━━━━━ 편집 데이터 기사, 프레임 [필터링된 Vision]" as Z2 #FFF3B3 rectangle "foundry/private/ (원 3) ━━━━━━ Code closed source [DATASET 비공개]" as Z3 #B3D9FF rectangle "foundry/public/ (3번째 원) ━━━━━━ 오픈 소스 코드 Apache 2.0 [자유 접근]" as Z4 #B3FFB3 } Z0 -[hidden]-> Z1 Z1 -[hidden]-> Z2 Z2 -[hidden]-> Z3 Z3 -[hidden]-> Z4 @enduml</pre> </div> </div> <div class="sect2"> <h3 id="_다섯_개_구역_공간_차원_rgpd">다섯 개 구역 (공간 차원 — RGPD)</h3> <div class="paragraph"> <p>워크스페이스의 각 영역에는 파일이 저장될 수 있는 *어디*를 결정하는 GDPR 수준이 있습니다. 라우팅되다 :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1682%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">구역</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">일반 개인정보 보호 규정 수준</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">내용</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">공개 RAG 접근 권한</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">뿌리</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">0 — 친밀한</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">브레인 덤프, LLM 대화</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>금지</strong>— 절대 색인되지 않음</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>configuration/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1 — 제한된 소유주</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">시크릿, 토큰, API 키</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>금지</strong>— 절대 색인되지 않음</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>office/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2 — 제한적 협업</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">편집 데이터, 구도, 교육</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>필터링된</strong>— 시각만</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>foundry/private/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3 — 조건부 개방</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">소스 코드가 비공개인, 공개되지 않은 SaaS</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>금지</strong>— 전용 프라이빗 데이터셋</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>foundry/public/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">4 — 네이티브 대중</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">아파치 2.0 코드, 공개된 플러그인</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>자유</strong>— 전체 색인</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>규칙은 간단합니다: <strong>파일 경로가 LLM이 그것을 할 수 있는 것을 결정합니다.</strong> 유지해야 할 메타데이터도 없고, frontmatter에 추가할 태그도 없습니다, 각 커밋마다 수동 분류는 없습니다. 파일이 …​에 있습니다.<code>OSS/</code>? 공개되어 있습니다. 안에 있습니다`configuration/`? 그는 손댈 수 없다.</p> </div> </div> <div class="sect2"> <h3 id="_인식론적_분류_두_번째_차원">인식론적 분류 (두 번째 차원)</h3> <div class="paragraph"> <p>공간 차원은 <strong>어디*로 라우트할지를 말한다. 하지만 수직인 두 번째 축이 있습니다: *뭐</strong> 라우터. 일부 파일은 허가된 구역에 있는 정보를 포함하고 있습니다. 희석해서는 안 되는 것들:</p> </div> <div id="diag-epistemic-filter" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 240 title 이중 캐스케이드 — 공간 필터 + 인식론적 필터 start :Le LLM rencontre un fichier; if (Zone physique ?) then (Cercle 0-1) :ACCÈS BLOQUÉ\n(secret, brain dump); stop elseif (Zone CSS/) :DROIT D'ACCÈS PRIVÉ\n→ dataset fine-tuning; :Filtre épistémique\nVision/Opinion; if (Classification ?) then (VISION) :Dataset privé\n→ entraînement autorisé; else (OPINION) :CONFINÉ\n→ pas d'entraînement; endif elseif (Zone office/) :DROIT D'ACCÈS FILTRÉ\n→ accès conditionnel; :Filtre épistémique\nVision/Opinion/Stratégie; if (Classification ?) then (VISION) :DILUTION COMPLÈTE\n→ docs racine + blog; elseif (STRATÉGIE) :DILUTION RESTREINTE\n→ docs racine seulement; else (OPINION) :CONFINEMENT\n→ office/ uniquement; endif else (Zone OSS/) :ACCÈS LIBRE\n→ indexation complète; endif stop @enduml</pre> </div> </div> <div class="paragraph"> <p>에피스테믹 분류 그리드, 나의 통치에 새겨진 규칙 2bis 에이전트 :</p> </div> <div class="paragraph"> <p>| 상태 | 정의 | LLM 신호 | 목적지 | | 비전 | 안정된 아키텍처, 테스트된 패턴 | 선언적 언어, 세션/테스트 참조 | 완전한 희석 + 블로그 | | 전략 | 비즈니스 포지셔닝, 가격 | 시장 어휘, 경쟁 | 루트 문서만 | | OPINION | 추측, 검증되지 않은 가설 | 가설적 언어, 직감 | 격리 구역 0 |</p> </div> <div class="paragraph"> <p>두 차원의 결합 — 물리적 영역 × 인식론적 분류 — 형의<strong>완전한 행렬</strong>:</p> </div> <div id="diag-full-matrix" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE title 완전한 매트릭스 — 구역 × 분류 salt { {T + Zone | VISION | STRATÉGIE | OPINION + Racine (0) | ✗ Interdit | ✗ Interdit | ✗ Interdit + configuration/ (1) | ✗ Interdit | ✗ Interdit | ✗ Interdit + office/ (2) | ✓ Docs + Blog | ✓ Docs seulement | ✗ Confiné + CSS/ (3) | ✓ Dataset privé | ✓ Dataset privé | ✗ Confiné + OSS/ (4) | ✓ Public libre | ✓ Public libre | ✓ Public libre } } @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_llm이_이_행렬을_어떻게_소비하는가">LLM이 이 행렬을 어떻게 소비하는가</h2> <div class="sectionbody"> <div class="paragraph"> <p>행렬은 LLM이 읽는 문서가 아닙니다. 이것은 <strong>제약 암시된</strong> 인코딩된 컨텍스트 복합 벡터에 (EPIC 9 — 진행 중 구현의)</p> </div> <div class="paragraph"> <p>다음은 LLM이 각 세션에서 받는 내용 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">VECTEUR COMPOSITE DE CONTEXTE ├── RAG pgvector → OSS/ + office/Vision │ (similarité sémantique sur contenu publiable) ├── Knowledge Graph graphify → OSS/ │ (relations exactes entre artéfacts publics) ├── Knowledge Graph privé → CSS/ │ (relations entre code closed source — jamais exporté) ├── Métadonnées de zone → chaque fichier taggé par zone physique │ (le LLM sait s'il est dans office/ ou OSS/) └── Historique des décisions → WORKSPACE_VISION.adoc (contexte temporel des arbitrages)</code></pre> </div> </div> <div class="paragraph"> <p>구체적으로, LLM이 내게 말할 때:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">Je vais indexer le contenu de edster/ pour enrichir le knowledge graph...</code></pre> </div> </div> <div class="paragraph"> <p>영역 메타데이터는 LLM이 문장을 마치기도 전에 응답합니다 : <code>edster/`에 있다`CSS/</code>, 레벨 3 →<strong>공개 지식 그래프에 대한 접근이 금지되었습니다.</strong> RAG는 그것을 보지 못한다. 그래프는 그것을 만지지 않는다. 사용자 응답은 그는 그것을 인용하지 않는다.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>공간 온톨로지는처럼 작동한다<strong>유닉스 권한</strong>LLM용. 당신은 프로세스가 조심하기를 요구하지 않는다`/etc/shadow`— 그에게 읽기 접근을 거부합니다. 같은 원칙입니다.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_구현_타입이_지정된_gradle_작업">구현 : 타입이 지정된 Gradle 작업</h2> <div class="sectionbody"> <div class="paragraph"> <p>매트릭스는 철학이 아니다. 이것은 코드이다. 다음은 작업 계약이다. 구현한 Gradle :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">abstract class ZoneAwareIndexer @Inject constructor( private val rootDir: DirectoryProperty, private val configServer: ConfigServerProperty // → configuration/ ) : DefaultTask() { @Input val zoneFilter: SetProperty<Zone> = project.objects.setProperty(Zone::class.java) @OutputFile val ragIndex: RegularFileProperty = project.objects.fileProperty() @TaskAction fun index() { val allowedPaths = zoneFilter.get().flatMap { it.resolve(rootDir.get()) } val forbiddenPaths = Zone.RESTRICTED.resolve(rootDir.get()) + Zone.INTIMATE.resolve(rootDir.get()) // Le RAG ne voit jamais configuration/ ni la racine // CSS/ alimente un index privé, pas celui-ci // office/ est filtré par le classifieur Vision/Opinion } } enum class Zone { INTIMATE, // Cercle 0 — racine RESTRICTED, // Cercle 1 — configuration/ EDITORIAL, // Cercle 2 — office/ CLOSED_SOURCE, // Cercle 3 — foundry/private/ OPEN_SOURCE // Cercle 3 — foundry/public/ }</code></pre> </div> </div> <div class="paragraph"> <p>작업은 *testable*입니다. 검증할 수 있는 테스트를 작성할 수 있습니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `le RAG n'indexe jamais configuration`() { val index = ZoneAwareIndexer(rootDir, configServer) index.zoneFilter.set(setOf(Zone.OPEN_SOURCE, Zone.EDITORIAL)) index.index() assertThat(index.ragIndex).doesNotContain("configuration/") } @Test fun `le code closed source est exclu du RAG public`() { val index = ZoneAwareIndexer(rootDir, configServer) index.zoneFilter.set(setOf(Zone.OPEN_SOURCE)) // OSS only assertThat(index.ragIndex).doesNotContain("edster") }</code></pre> </div> </div> <div class="paragraph"> <p>380 테스트, 380 통과. plantuml-gradle처럼 — 보안이 테스트됨, 예상치 못한</p> </div> </div> </div> <div class="sect1"> <h2 id="_왜_이것이_선언문이지_단순한_사양이_아닌가">왜 이것이 선언문이지, 단순한 사양이 아닌가?</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 문서는 아키텍처 사양입니다. 왜냐하면 다음과 같이 정의하기 때문입니다 :</p> </div> <div class="ulist"> <ul> <li> <p>몇<strong>치수</strong>(공간적, 인식론적)</p> </li> <li> <p>몇몇<strong>결정론적 규칙</strong>(구역 → 접근 권한)</p> </li> <li> <p>Un <strong>과업 계약</strong>(타입된 Gradle, 테스트 가능한)</p> </li> <li> <p>하나<strong>참조 구현</strong>(내 워크스페이스)</p> </li> </ul> </div> <div class="paragraph"> <p>하지만 그것은 또한<strong>선언문</strong>그는 논쟁에 입장을 취하기 때문에 더 큰: <strong>LLM의 데이터 접근을 어떻게 관리할 수 있을까?</strong></p> </div> <div class="paragraph"> <p>산업계의 답은 프롬프트 엔지니어링 + 가드레일<br> 사후 분류기. 내 답변은 : <strong>당신의 파일을 안에 올바른 파일들.</strong> 나머지는 자동입니다.</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>이 선언문은 "LLM은 정렬되어야 한다"고 말하지 않습니다. 그것은 말합니다 : "정렬 당신의 보안 규칙에 대한 LLM은 당신의 시스템의 결과이다 파일, 당신의 프롬프트가 아닙니다.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_완전한_폭포_brain_dump에서_블로그_글까지">완전한 폭포 — Brain Dump에서 블로그 글까지</h2> <div class="sectionbody"> <div class="paragraph"> <p>완전한 주기를 보여주기 위해, 이 행렬 아이디어가 어떻게 탄생했는지 보여줍니다 그리고 희석되었습니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">Session 4 mai 2026 — Feedback global du workspace │ ├→ Le LLM identifie : "la dualité public/privé est invisible" │ → Classifié VISION (constat architectural vérifiable) │ ├→ PICTURE_ME_ROLLIN_MATRICE_4X4.adoc — STIMULUS (Cercle 0) │ → Brain dump structuré, classification VISION confirmée │ ├→ DILUTION → WORKSPACE_AS_PRODUCT.adoc (section Matrice 4×4) │ → La spec vit dans les documents racine │ ├→ DILUTION → WORKSPACE_ORGANIZATION.adoc (OSS/CSS) │ → La granularisation est documentée │ └→ ARTICLE 0117 (ce document) → cheroliv.com → La VISION est publiée</code></pre> </div> </div> <div class="paragraph"> <p>세션 중에 이루어진 관찰로 시작된 것 ("야, RAG은 몰라 에드스터가 closed source가 되었다") 아키텍처 사양이 되었다 한 세션 미만으로 발표되었습니다. 이것이 STIMULUS 패턴이 동작 중입니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_찬성반대">찬성/반대</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">이 접근법 (공간 온톨로지 + 행렬)</th> <th class="tableblock halign-left valign-top">클래식 접근법 (프롬프트 + 가드레일)</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>기계</strong> — 파일 시스템이 접근을 차단하고, LLM은 아니다</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>선언적</strong> — 프롬프트가 LLM에게 신중하도록 요청합니다</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Testable</strong> — Gradle 태스크 계약은 380개 이상의 테스트에 의해 검증됩니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>테스트할 수 없는</strong> — "LLM이 규칙을 따랐나요?"는 개방형 질문입니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">LLM에 독립적입니다 — 모델을 바꾸면, 폴더는 그대로 유지됩니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>LLM에 의존하는</strong> — 각 모델은 프롬프트를 다르게 해석합니다</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>확장 가능</strong> — 새로운 데이터 유형 = 새 폴더, 코드 변경 없음</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>확장 불가능한</strong> — 새로운 데이터 유형 = 새로운 프롬프트 조항, 새로운 회귀 위험</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Auditable</strong> — 파일 시스템은 감사 추적입니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>감사할 수 없는</strong> — 프롬프트는 기록이 없고, diff가 없고, 비난이 없다</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>제약</strong> : 초기 조직적 규율을 요구한다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>제약</strong> : 매 세션마다 프롬프트 작성의 규율을 요구한다</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_결론_파일을_정리하고_프롬프트를_정리하지_마세요">결론: 파일을 정리하고, 프롬프트를 정리하지 마세요.</h2> <div class="sectionbody"> <div class="paragraph"> <p>내가 방금 설명한 LLM 거버넌스 매트릭스는 제품이 아닙니다. 이것은 하나의<strong>아키텍처 사양</strong>— 그녀가 그런 거야. 게시 가능한.</p> </div> <div class="paragraph"> <p>그녀를 강건하게 만드는 것은, 그녀가 LLM에 아무것도 요구하지 않기 때문이다. 그녀는 그에게 믿지 않는다. 그것은 그의 정렬이나 이해에 의존하지 않는다. 프랑스어의, 또는 그녀의 선의에 달려 있습니다. 그녀는 파일 시스템에 기반을 두고 있습니다 — 전체 스택에서 가장 낮고, 가장 안정적이며, 가장 테스트된 계층.</p> </div> <div class="paragraph"> <p>내가 내 LLM에게 '모든 것을 인덱싱할 수 있어’라고 말할 때`OSS/<code>, 아무것도 `configuration/</code>, et <code>office/</code> 그것 Vision으로 분류된 경우에만" — 이것은 지시가 아닙니다. 이것은 <strong>필터</strong> — Kotlin에서 구현된, 380 테스트에 의해 검증됨, LLM이 데이터를 보기 전에 실행됨</p> </div> <div class="paragraph"> <p>그 사람에게 "이 서랍을 보지 마"라고 말하는 것과의 차이입니다 그리고 열쇠 서랍을 닫습니다. 내가 지금까지 구축하고 있는 에이전트 거버넌스 개월이 핵심이다. 매트릭스는 가구의 도면이다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_참고문헌">참고문헌</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0116_compartimentage_epistemique_automatise_llm_post.html">논문 0116 — 자동화된 인식론적 구획</a></p> </li> <li> <p>제 0114조 — 신뢰의 원과 공간 온톨로지</p> </li> <li> <p><a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">문서 0108 — AsciiDoc을 사용하여 AI 에이전트 관리하기</a></p> </li> <li> <p><a href="../2026/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html">Article 0115 — 익명화 도구 MVP0</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0117_granularisation_oss_css_repositorie_workspace_post.html Sun, 3 May 2026 00:00:00 +0000 blog/2026/0117_granularisation_oss_css_repositorie_workspace_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_일어나기를_기다리던_사고">일어나기를 기다리던 사고</a> <ul class="sectlevel2"> <li><a href="#_진짜_질문">진짜 질문</a></li> </ul> </li> <li><a href="#_해결책_oss_및_css">해결책 : OSS/ 및 CSS/</a></li> <li><a href="#_왜_oss와_css이며_public과_private가_아닌가">왜 "OSS"와 "CSS"이며 "Public"과 "Private"가 아닌가</a> <ul class="sectlevel2"> <li><a href="#_완전한_나무_네_구역_세_구역이_아님">완전한 나무 — 네 구역, 세 구역이 아님</a></li> </ul> </li> <li><a href="#_특별한_경우_cheroliv_com">특별한 경우: cheroliv.com</a> <ul class="sectlevel2"> <li><a href="#_bakery_gradle_신경_쓰지_않는다">bakery-gradle 신경 쓰지 않는다</a></li> </ul> </li> <li><a href="#_거버넌스_에이전트에_미치는_영향">거버넌스 에이전트에 미치는 영향</a></li> <li><a href="#_우리가_얻는_것_그리고_우리가_잃는_것">우리가 얻는 것 (그리고 우리가 잃는 것)</a></li> <li><a href="#_결론_물리적_신호가_소프트웨어_신호를_이긴다">결론 : 물리적 신호가 소프트웨어 신호를 이긴다</a></li> <li><a href="#_참조">참조</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽는 시간: 10 minutes</div> <p><code>foundry/</code>— 내 워크스페이스 코드를 호스팅하는 기능 영역 — 18개의 프로젝트를 포함하고 있습니다. 여덟 개는 Apache 2.0 라이선스 하에 오픈 소스입니다. 단 하나만 closed source — SaaS Edster. 몇 달 동안, 이 아홉 개의 프로젝트가 공존했습니다. 같은 폴더에 있으며, 아무것도 없이 단순히…​ 구분되어 있습니다. 공개/비공개 상태 그건 내 머리 속의 정보였지, 파일 시스템의 정보가 아니었어.</p> </div> <div class="paragraph"> <p>그리고 나서 RAG를 연결하고 싶었어요. 그러자 모든 것이 무너졌습니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_일어나기를_기다리던_사고">일어나기를 기다리던 사고</h2> <div class="sectionbody"> <div class="paragraph"> <p>2026년 4월에, 저는 slider-gradle를 위해 RAG pgvector 구현을 시작했습니다. 원칙 : 모든 저장소를 색인하는`foundry/<code>, 생산하다 embeddings, 이를 LLM의 컨텍스트에 주입하여 그것이 하나의 perception" 파일에 대한 인식`foundry/</code>.</p> </div> <div class="paragraph"> <p>파이프라인은 간단했습니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val repos = fileTree(rootDir) { include("**/*.adoc", "**/*.kts", "**/*.kt", "**/*.json", "**/*.yml") } val chunks = repos.map { chunk(it) } val embeddings = chunks.map { embed(it) } pgvector.insert(embeddings)</code></pre> </div> </div> <div class="paragraph"> <p>간단함. 효과적. 그리고<strong>위험한</strong>.</p> </div> <div class="paragraph"> <p>왜냐하면 이것이`fileTree`사이에 차이를 두지 않다`plantuml-gradle/` (Apache 2.0, public) 그리고`edster/`(closed source, private).그는 tudo를 다 삼킨다. 그리고 언젠가 내가 이 임베딩을 게시한다면 — 대시보드에서, 응답에서 LLM, 훈련 데이터셋에서 — Edster의 독점 코드가 유출됩니다.</p> </div> <div class="admonitionblock caution"> <table> <tr> <td class="icon"> <i class="fa icon-caution" title="🔒"></i> </td> <td class="content"> <div class="paragraph"> <p>문제는 LLM이 닫힌 소스 코드를 읽는 것이 아니다. 문제는, 이 코드가 <strong>공개된</strong> 벡터 임베딩에 들어가게 되는 것이다 — 되돌릴 수 없는, 삭제할 수 없는, 감사할 수 없는.</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_진짜_질문">진짜 질문</h3> <div class="paragraph"> <p>이건 "LLM이 코드를 누출하는 것을 어떻게 막을 수 있나요?"가 아닙니다. 이건 "어떻게"입니다 도주를 구조적으로 불가능하게 만들 수 있나요 ?</p> </div> <div class="paragraph"> <p>답변은 프롬프트가 아닙니다. 답변은 폴더를 두 조각으로 자르는 것입니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_해결책_oss_및_css">해결책 : OSS/ 및 CSS/</h2> <div class="sectionbody"> <div class="paragraph"> <p>이전:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">foundry/ ├── plantuml-gradle/ ← public ├── bakery-gradle/ ← public ├── magic-stick/ ← public ├── edster/ ← PRIVÉ ├── slider-gradle/ ← public └── ... ← mélange invisible</code></pre> </div> </div> <div class="paragraph"> <p>다음 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">foundry/ ├── OSS/ ← tout est Apache 2.0 │ ├── plantuml-gradle/ │ ├── bakery-gradle/ │ ├── magic-stick/ │ ├── slider-gradle/ │ └── ... └── CSS/ ← tout est closed source / private └── edster/</code></pre> </div> </div> <div class="paragraph"> <p>Le `fileTree`된다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val ossRepos = fileTree(File(rootDir, "OSS")) { include("**/*.adoc", "**/*.kts", "**/*.kt", "**/*.json", "**/*.yml") } val cssRepos = fileTree(File(rootDir, "CSS")) { include("**/*.adoc", "**/*.kts", "**/*.kt", "**/*.json", "**/*.yml") } // Embeddings publics — OSS seulement pgvectorPublic.insert(ossRepos.map { chunk(it) }.map { embed(it) }) // Dataset fine-tuning privé — CSS seulement fineTuningDataset.insert(cssRepos.map { chunk(it) }) // jamais publié</code></pre> </div> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>공개된 RAG은 결코 보지 않는다.<code>CSS/</code>. 폐쇄 소스 코드가 데이터셋을 공급한다 파인튜닝 없이 — 내 집에서 절대 나가지 않는 내부 모델. 그 분리는 기계적이며 선언적이지 않습니다.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_왜_oss와_css이며_public과_private가_아닌가">왜 "OSS"와 "CSS"이며 "Public"과 "Private"가 아닌가</h2> <div class="sectionbody"> <div class="paragraph"> <p>OSS(Open Source Software)와 CSS(Closed Source Software)라는 약어 선택 의논된 :</p> </div> <div class="ulist"> <ul> <li> <p>Public"/"Private"는<strong>가시성</strong>(GitHub이 보는 것)</p> </li> <li> <p>OSS"/"CSS" 는 설명하는<strong>자연</strong>코드 (LLM이 알아야 할 것)</p> </li> </ul> </div> <div class="paragraph"> <p>GitHub 가시성은 원격 저장소의 메타데이터입니다. 코드의 성격은 내용의 속성. LLM은 GitHub API에 접근할 수 없지만 — 그러나 접근할 수 있습니다. 파일 시스템에.<code>CSS/`그는 그에게 "주의, 이 코드는 라이선스가 없습니다"라고 말했다. 자유" 를 읽을 필요 없이`LICENSE`또는 하나를 파싱하는`package.json</code>.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>폴더 이름은 당신이 줄 수 있는 가장 강력한 메타데이터입니다 한 LLM. 잘못 파싱될 수 없고, 무시될 수도 없고, 잘못 해석될 수도 없습니다. 이 LLM 본다`CSS/edster/`파일 경로에서 — 그는 알고 있다.</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_완전한_나무_네_구역_세_구역이_아님">완전한 나무 — 네 구역, 세 구역이 아님</h3> <div class="paragraph"> <p>OSS/CSS 세분화는 3영역 온톨로지를 완성한다. 영역 `foundry/`기능적 하위 구역이 1에서 2로 변경됩니다 :</p> </div> <div id="diag-four-zone-workspace" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 260 title foundry 조직 — OSS/CSS 세분화 package "주조소/" { package "원 0 — 근원" #FFCCCC { rectangle "PICTURE_ME_ROLLIN_*.adoc" as STIM rectangle "WORKSPACE_*.adoc" as VISION_DOC note right of STIM Brain dump libre Jamais versionné [LLM : interdit d'indexer] end note } package "원 1 — 설정/" #FFD9CC { rectangle "비밀, 토큰" as SECRETS rectangle "Spring Cloud Config" as SCC note right of SECRETS Privé-CVS, solo access [LLM : INTERDIT] end note } package "원 2 — 사무실/" #FFFFCC { rectangle "기사, 구도" as DATA rectangle "훈련, SPG/SPD" as FORM note right of DATA Privé-CVS [LLM : filtré Vision/Opinion] end note } package "원 3 — 주조/" #CCE5FF { package "OSS/ — 아파치 2.0" #CCFFCC { rectangle "그레이들 플러그인" as PLUGINS rectangle "엔진" as ENGINE } package "CSS/ — 폐쇄 소스" #CCDDFF { rectangle "edster/" as EDSTER } } } @enduml</pre> </div> </div> <div class="paragraph"> <p>| 구역 | 개인정보 보호 규정 | 공개 RAG 인덱싱 | 데이터셋 파인튜닝 | | 뿌리 | 수준 0 — 친밀한 | ✗ | ✗ | | <code>configuration/</code>| 레벨 1 — 제한됨 | ✗ | ✗ | | <code>office/</code>| 레벨 2 — 협업적 | ✓ 필터된 | ✓ 필터된 | | <code>foundry/private/</code>| 레벨 3 — 조건부 개방 | ✗ | ✓ 비공개 | | <code>foundry/public/</code>| 레벨 4 — 원어민 | ✓ 무료 | ✓ 공개 |</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_특별한_경우_cheroliv_com">특별한 경우: cheroliv.com</h2> <div class="sectionbody"> <div class="paragraph"> <p>거기 있을 때, 나는 또 다른 불일치를 수정했다. 내 사이트 <code>cheroliv.com`살고 있던`foundry/`소프트웨어 프로젝트처럼 완전한 — 자체 Gradle 빌드, 자체 CI, 자체 거버넌스</code>.agents/`.</p> </div> <div class="paragraph"> <p>하지만 블로그 글은 코드가 아닙니다. <strong>데이터</strong>입니다 사설들** 의 Cercle 2 — 같은 기준으로 프레이밍 의`office/pilotage/` 또는 형성의`office/formations/`.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">AVANT APRÈS foundry/ office/ cheroliv.com/ sites/ site/jbake/content/blog/ cheroliv.com/ 2026/0117_....adoc 2026/0117_....adoc</code></pre> </div> </div> <div class="paragraph"> <p>변경되는 것:</p> </div> <div class="ulist"> <ul> <li> <p>물건들은 안에 있습니다.<code>office/</code>→ Cercle 2의 기밀성</p> </li> <li> <p>작업`publishSite`의 하나의 능력이 된다`engine`</p> </li> </ul> </div> <div class="paragraph"> <p>통해`bakery-gradle`— 플러그인이 하나를 받는다`FileTree`, 그는 모른다 기사들이 오는`office/`</p> </div> <div class="ulist"> <ul> <li> <p>한 개의 CI, 한 개의 거버넌스 — 중복 없음</p> </li> <li> <p>Vision/Opinion 분류기(규칙 2bis)는 자동으로 적용됩니다:</p> </li> </ul> </div> <div class="paragraph"> <p>기사들 안에`office/`출판 전에 필터링됩니다</p> </div> <div class="sect2"> <h3 id="_bakery_gradle_신경_쓰지_않는다">bakery-gradle 신경 쓰지 않는다</h3> <div class="paragraph"> <p>그리고それが 아름다워요. 플러그인`bakery-gradle`수정되지 않았습니다. 그는 AsciiDoc 콘텐츠 디렉터리를 받고, HTML을 생성하고, 푸시한다. GitHub Pages에서. 이 디렉터리가`site/jbake/content/` ou <code>office/sites/cheroliv/</code>— 플러그인은 신경 쓰지 않는다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// engine/build.gradle.kts task("publishBlog") { doLast { val articles = fileTree("../../office/sites/cheroliv/2026/") bakery.generate(articles) // ← bakery ne sait pas d'où ça vient } }</code></pre> </div> </div> <div class="paragraph"> <p>인터페이스 계약은 Gradle 작업입니다. REST API가 아닙니다. 웹훅이 아닙니다. 한 작업 — 타입이 지정된, 테스트 가능한, 로컬 및 CI에서 실행 가능한.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_거버넌스_에이전트에_미치는_영향">거버넌스 에이전트에 미치는 영향</h2> <div class="sectionbody"> <div class="paragraph"> <p>OSS/CSS 세분화는 세 가지 측면에서 에이전트 거버넌스를 변경합니다:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>RAG public</strong> : 색인 범위가 이동됩니다`foundry/**`</p> </li> </ol> </div> <div class="paragraph"> <p>à <code>foundry/public/<strong></code>+<code>office/Vision/</strong></code>. 폐쇄 소스 코드 작업 구성에 의해 인덱스에서 제외되며, 프롬프트에 의해 제외되지 않습니다.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Knowledge Graph</strong> : graphify-gradle 두 개의 그래프를 생성합니다 :</p> </li> </ol> </div> <div class="paragraph"> <p>*<code>office/graph.json</code>(public) — OSS 아티팩트와 office/Vision 사이의 관계 *<code>configuration/graph_private.json</code>(gitignored, 비공개의) — 관계 사이 CSS 아티팩트, 절대 게시되지 않음</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>데이터셋 파인튜닝</strong> :`codebase-gradle`이제 두 개의 출처가 있습니다:</p> </li> </ol> </div> <div class="paragraph"> <p>*<code>OSS/</code>→ 공개 데이터세트 (커뮤니티 모델, 벤치마크) *<code>CSS/</code>→ 개인 데이터 세트 (내부 모델, 독점적 파인튜닝)</p> </div> </div> </div> <div class="sect1"> <h2 id="_우리가_얻는_것_그리고_우리가_잃는_것">우리가 얻는 것 (그리고 우리가 잃는 것)</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1436%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">이전 (평면 폴더)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">다음에 (OSS/CSS + office/sites)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>ls foundry/</code>→ 공공/사적 혼합</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>ls foundry/public/</code>→ 모든 것이 게시 가능합니다</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">RAG는 차별 없이 모든 것을 인덱싱합니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">RAG은 인덱싱합니다`OSS/`+`office/Vision`오직</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">프로젝트가 오픈 소스인지 알 수 없습니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">길`OSS/` ou `CSS/`위에서 언급한</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">cheroliv.com은 자체 CI, 자체 거버넌스를 가지고</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">CI와 거버넌스는 engine 내에서 공유됩니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">블로그 글은 "code" 저장소에 있습니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">블로그 게시물은`office/sites/`— 데이터, 코드가 아님</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">공개 임베딩에서의 폐쇄 소스 코드 유출 위험</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">구조적으로 불가능 —`CSS/`범위를 벗어난 RAG</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>유일한 비용 : 하나`git mv`전 세계 17개 OSS 저장소에 대한 + 리팩터링된 <code>build.gradle.kts</code> de <code>engine</code>. 이것은 콜드 마이그레이션 — 비행 중인 데이터도 없고, 영향을 받은 사용자도 없습니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_결론_물리적_신호가_소프트웨어_신호를_이긴다">결론 : 물리적 신호가 소프트웨어 신호를 이긴다</h2> <div class="sectionbody"> <div class="paragraph"> <p>오늘 오후에 내가 한 일은 보이지 않는 관행을 대체한 것이었다. 구역 안에서 보이는 분리로`foundry/<code>.이전에는, 당신은 해야 했습니다. <strong>알다</strong> 고`edster/`폐쇄 소스였습니다. 이제 당신이 그것을 <strong>봅니다</strong> — 폴더 이름은`CSS/</code>.</p> </div> <div class="paragraph"> <p>이것은 Unix 권한, 네트워크 VLAN, 또는 그것과 동일한 원리입니다. 데이터베이스의 방화 구획. 보안은 해서는 안 된다 당신이 기억해야 할 정보여야 합니다. 그것은 속성이어야 합니다. <strong>물리학</strong>시스템의.</p> </div> <div class="paragraph"> <p>OSS/CSS 세분화는 이 분야에서의 이 원칙의 번역이다. LLM 거버넌스. LLM은 Edster가 무엇인지 알 필요가 없습니다. 기밀. 그는 그것을 색인할 수 없어야 한다.</p> </div> <div class="paragraph"> <p>그리고 그것은 정확히`CSS/`보장한다</p> </div> </div> </div> <div class="sect1"> <h2 id="_참조">참조</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>문서 0117 — LLM 거버넌스 매트릭스</p> </li> <li> <p><a href="0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html">Article 0114 — 신뢰의 원</a></p> </li> <li> <p><a href="0116_compartimentage_epistemique_automatise_llm_post.html">문서 0116 — 자동화된 인식론적 구분</a></p> </li> <li> <p><a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">Article 0108 — AsciiDoc으로 IA 에이전트를 관리하기</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0116_compartimentage_epistemique_automatise_llm_post.html Sat, 2 May 2026 00:00:00 +0000 blog/2026/0116_compartimentage_epistemique_automatise_llm_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_문제_자유롭게_생각하기_아무것도_게시하지_않기">문제 : 자유롭게 생각하기, 아무것도 게시하지 않기</a></li> <li><a href="#_stimulus_패턴_태어나다_고정하다_희석하다_죽다">STIMULUS 패턴 — 태어나다, 고정하다, 희석하다, 죽다</a></li> <li><a href="#_llm에_위임_왜_llm이_필터링을_하는가">LLM에 위임: 왜 LLM이 필터링을 하는가</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽기 시간 : 10 minutes</div> <p>내 LLM은 단순히 내 Gradle 작업을 실행하는 것에 만족하지 않는다. 그것은 내 비공개 생각과 공개 표현 사이의 경계를 지키는 수호자이다. 모든 아이디어는 라우팅되기 전에 — 비전, 의견, 전략 — 으로 분류된다. 이것이 자동화된 인지론적 구분이 나의 정신 정원을 침묵시키지 않으면서 보호하는 방식이다.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">틱</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_문제_자유롭게_생각하기_아무것도_게시하지_않기">문제 : 자유롭게 생각하기, 아무것도 게시하지 않기</h2> <div class="sectionbody"> <div class="paragraph"> <p>혼자 일하는 개발자가 LLM과 함께 자신의 사고 과정을 문서화할 때, 그는 하나의 역설에 직면한다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">CAPTURE TOUT (Cercle 0, jardin secret) ├→ Brain dump libre, pas de censure ├→ Idées brutes, spéculations, intuitions non vérifiées ├→ Allers-retours LLM : challenger, itérer, raffiner └→ Le LLM voit TOUT — le bon, le flou, l'embryonnaire PUBLICATION SÉLECTIVE (Cercle 4, blog public) ├→ Uniquement les décisions actées ├→ Uniquement les patterns testés (>100 tests PASS) ├→ Uniquement ce qui a de la valeur pour le lecteur └→ JAMAIS une spéculation présentée comme une vérité</code></pre> </div> </div> <div class="paragraph"> <p>이 두 극단 사이에 하나가<strong>필터</strong>. 이 질문은 : 누가 이것을 하는가? 피곤한 인간(세션 끝에)? 순진한 regex 스크립트? 아니면 LLM 자신이, 이미 모든 것을 읽은 것인가?</p> </div> <div class="paragraph"> <p>내 답변: LLM.</p> </div> </div> </div> <div class="sect1"> <h2 id="_stimulus_패턴_태어나다_고정하다_희석하다_죽다">STIMULUS 패턴 — 태어나다, 고정하다, 희석하다, 죽다</h2> <div class="sectionbody"> <div class="paragraph"> <p>STIMULUS는 파일입니다.<code>.adoc`워크스페이스 루트(서클 0)에 임시로 위치하고, 그 이름은 느낌을 주는 명명 규칙을 따릅니다 —`PICTURE_ME_ROLLIN.adoc</code>, <code>HOLD_MY_BEER.adoc</code>, <code>ONCE_UPON_A_TIME.adoc</code>— 현재의 탐색적 의도를 포착하는.</p> </div> <div class="paragraph"> <p>그의 삶의 주기는 냉혹합니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">CRÉATION (Cercle 0) ├→ Fichier vide, brain dump libre ├→ Allers-retours LLM ← → développeur └→ Aucune pression de structure ou de publication MATURATION ├→ Le contenu se densifie ├→ Des sections émergent naturellement └→ Le fichier devient une référence informelle de session CLASSIFICATION ÉPISTÉMIQUE ← FAIT PAR LE LLM ├→ VISION → publiable, diluer dans les docs publics + blog ├→ OPINION → confiner au Cercle 0, pas de dilution externe └→ STRATÉGIE → dilution restreinte (docs racine, PAS de blog) DILUTION (Cascade vers Cercles légitimes) ├→ VISION → WORKSPACE_AS_PRODUCT.adoc + WHAT_THE_GAMES.adoc + blog ├→ STRATÉGIE → WORKSPACE_AS_PRODUCT.adoc (section business) └→ OPINION → reste dans le stimulus, ne bouge pas ARCHIVAGE + SUPPRESSION ├→ Snapshot dans configuration/vision-archive/ (trace historique) └→ rm du stimulus — il a fini son travail</code></pre> </div> </div> <div class="paragraph"> <p>2회 이상의 세션을 거치지 않고 살아남는 자극은 안티-패턴입니다. 정보가 임시 파일에서 썩히기엔 너무 중요하다면(→ 희석), 존재할 가치가 있을 만큼 명확하지 않다면(→ 삭제).</p> </div> </div> </div> <div class="sect1"> <h2 id="_llm에_위임_왜_llm이_필터링을_하는가">LLM에 위임: 왜 LLM이 필터링을 하는가</h2> <div class="sectionbody"> <div class="paragraph"> <p>나는 Kotlin에서 Vision/Opinion 분류를 하드코딩하지 않습니다. 나는 그것을 안에 주입한다.<strong>시스템 프롬프트</strong>LLM을 통해`AGENT_GOVERNANCE.adoc` :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- ---- Pour chaque dilution de stimulus ou session, tu es responsable de classifier le contenu : - VISION : décision architecturale actée, pattern testé en production (>100 tests PASS), décision documentée dans BACKLOG ou ROADMAP - OPINION : spéculation, hypothèse non validée par des tests, intuition sans ancrage expérimental - STRATEGIE : positionnement business, pricing, marché cible Règles : - Si OPINION, le contenu reste confiné dans son cercle d'origine - Si VISION, tu procèdes à la dilution dans les documents racine - Si STRATEGIE, dilution restreinte (docs racine, pas de blog public) - Cette classification détermine aussi si un article de blog est publiable sur cheroliv.com ---- LLM은 이 지시를 읽는다**이전**세션을 처리하는 것. 그것은 별도의 파일이 아닌 즉시적인 컨텍스트에 있습니다. *결정적 프롬프트 엔지니어링* : 행동은 외부 분류자가 아닌 주입된 텍스트에서 발생합니다. === 왜 작동하는가 — 그리고 왜 직관과 반대되는가 표준 반응 : « AI에게 분류를 맡기나요? 실수하면 어쩌려고? 답변: 인간은 새벽 2시에 더 잘하지 못한다. 차이점은 LLM이 모든 것을 읽는다는 점이다. 세션과 대상 문서의 전체 맥락을 가지고 있다. 그것은 알고 있다`VPS ECO-16 12€ HT`이는 인프라 의사결정(VISION)이며`« le TTS ElevenLabs sonne plus naturel que Coqui »`이는 벤치마크에 의해 검증되지 않은 의견입니다. 인간은 세션이 끝날 무렵 대각선으로 읽으며 최선을 다한다. LLM은 모든 것을 읽고 체계적인 격자를 적용한다. 결과는**더 신뢰할 수 있는**, 적어도. 그리고 20%의 애매한 경우 — 심지어 LLM조차 주저하는 회색 지대 — 에 대한 답은 '코드를 더 추가하는 것'이 아니다. 답은**LangGraph4j**(EPIC 13) : 모호한 경우에 Human-in-the-Loop 노드를 활성화하고 인간에게 결정을 맡기는 상태 그래프이지만, 명확한 경우의 80%에서는 LLM만으로 충분합니다. == 완전한 파이프: 브레인 덤프에서 블로그 게시물까지 다음은 아이디어 초안에서 게시된 기사까지 전체 흐름 — LLM만이 유일한 필터인 — : [source] ---- CERCLE 0 (jardin secret) PICTURE_ME_ROLLIN.adoc ← brain dump, allers-retours LLM ↓ [LLM classifie] → VISION / OPINION / STRATÉGIE ↓ VISION → dilution dans WORKSPACE_AS_PRODUCT.adoc → dilution dans WHAT_THE_GAMES_BEEN_MISSING.adoc → dilution dans WORKSPACE_VISION.adoc (session context) → RÉDACTION ARTICLE BLOG ← le LLM écrit, pas le dev ↓ CERCLE 4 (blog public) 0116_compartimentage_epistemique.adoc ← publié sur cheroliv.com ↓ ./gradlew deploy (bakery-gradle → JBake → JGit → GitHub Pages) ↓ https://cheroliv.com/blog/2026/0116/ ← live ---- 개발자는 기사를 작성하지 않는다. 그는 도전하고, 검토하고, 검증한다. LLM이 작성한다. 루프는 : 1. 브레인 덤프 자유 → 검열 없음 2. LLM에 의한 인식론적 분류 → 누수 없음 3. LLM에 의한 작성 → 미루지 않기 4. 인간 검토 → 오류 없음 역사적인 병목 현상 — « 시간을 낼 수 없다 » — 은 해소되었다. LLM이 대부분의 작업을 수행한다. 인간은 오직 인간만이 할 수 있는 일, 즉 판단한다. == 세 가지 루트 문서 — 정보가 제자리를 찾는 방법 각 대상 문서는 희석 캐스케이드에서 정확한 역할을 수행합니다: [cols="1,3,2"] |=== |문서 |그가 받는 것 |콘텐츠 유형 |`WORKSPACE_AS_PRODUCT.adoc` |아키텍처 결정, 기술 스택, 로드맵, 비즈니스 모델 |비전 + 전략 |`WHAT_THE_GAMES_BEEN_MISSING.adoc` |패턴, 수업, 안티패턴, 온톨로지, 형식적인 규칙 |비전 (테스트된 패턴) |`WORKSPACE_VISION.adoc` |세션 컨텍스트, 결정 기록, 인프라 포인트 |비전 + 전략 (맥락) |`AGENT_GOVERNANCE.adoc` |거버넌스 규정, 프로젝트 포트폴리오, 절차 |비전 (지배구조) |**블로그 cheroliv.com** |공개된 기사, 외부 독자를 위한 가치 |비전만 |=== 같은 자극이 4개의 문서와 블로그에 영양을 공급할 수 있다 — 각 목적지는 자신에게 해당하는 부분을 받으며, 중복도 모순도 없다. 이게 일어난 일`PICTURE_ME_ROLLIN.adoc`(2026년 5월 3일) : | Information | Classification | Destinations | | 인벤토리의 13+ 프로젝트 파운드리/ | 비전 | WORKSPACE_AS_PRODUCT | | VPS-2 OVH, edster.cloud, 월 8.49유로 | VISION | WORKSPACE_AS_PRODUCT + WORKSPACE_VISION | 아프리카 시장은 모바일 머니를 위해 준비되어 있다 » | STRATÉGIE | WORKSPACE_AS_PRODUCT (section business) | « DeepSeek > Kimi > GLM 장기 컨텍스트 » | OPINION → VISION | 제한되었다가 벤치마크 후 승진됨 (문서 0112) | | 합성 직원을 최종 제품으로 | 전략 | WORKSPACE_AS_PRODUCT (블로그 없음) | == Baby-Step 패턴 + TestContainer + 살아있는 문서 — 스스로 테스트하는 코드 이 패턴 `STIMULUS/Dilution`은 생각을 관리한다. 코드에서의 대응은 패턴 `Baby-Step/TestContainer/Doc Vivante`, 검증된 `plantuml-gradle (380/380 tests PASS, 137 sessions sans fuite Docker)` : [cols="1,3"] |=== |원칙 |규칙 |**아기 발걸음** |US당 3점을 초과하지 마시오. US가 두렵다면 나누시오. 통과하는 1점 US가 지연되는 8점 US보다 낫다. |**TestContainer 먼저** |비즈니스 코드 이전에 컨테이너. 인프라 테스트 통과 → 안정적인 환경 보장 |**커밋된 데이터셋** |최소한이면서도 대표적인 부분집합에서`src/test/resources/`, PII 없이. 복제 가능, 실행 가능. |**살아있는 문서** |각 Cucumber 테스트는 자연어 문장입니다. 소스 코드가 실행 가능한 명세입니다. 마크다운 문서를 유지할 필요가 없습니다. |**자동 정리** |자원 누수 없음. 고아 컨테이너,`/tmp/gradle-test-*`: 모든 것이 청소되었습니다. |=== 이 패턴이 138회 세션 동안 plantuml-gradle이 Docker 회귀를 한 번도 겪지 않은 이유입니다. 이것은 외부 인프라(PostgreSQL, Redis, Kafka)와 통신하는 코드가 항상 프로덕션과 동일한 환경에서 버전 관리되고, 재현 가능하며, 한 명령으로 실행 가능한 상태로 테스트된다는 것을 보장합니다. == 결론:출판에 대한 두려움 없이 생각의 자유 자동화된 인식론적 분할은 검열 도구가 아닙니다. 그것은**해방자**. 자유롭게 생각하고, 필터 없이 추측하며, 머리 속에 떠오르는 모든 것을 뇌 덤프한다 — 언제든 미성숙한 아이디어가 블로그에 올라올까 봐 두려워하지 않는다. LLM은 이 경계의 수호자이다. 그것은 모든 것을 읽는다. 그것은 분류한다. 그것은 생존할 가치가 있는 것을 희석시킨다. 그것은 비공개로 남아 있어야 할 것을 가두어 놓는다. 그것은 공개 가능한 것을 작성한다. 그리고 개발자는 마지막 말을 가진다 : 다시 읽고, 도전하고, 검증한다. 판단한다. 혼자 일하는 개발자에게 부족했던 것은 업무 분업이었습니다. 정신적인 paperwork을 처리하는 합성 직원이 있다면, 인간은 자신이 가장 잘하는 일—설계하고, 아키텍처를 구성하고, 결정을 내리는 것—에 집중할 수 있습니다. == 참고문헌 * 에이전트 Eager/Lazy 거버넌스에 대한 기사 :link:../2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[AsciiDoc을 사용한 AI 에이전트 관리] * 공간 온톨로지와 신뢰 원에 관한 기사 :link:../2026/0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html[공간 온톨로지, 정렬 메커니즘으로서] * Anonymiseur MVP0에 대한 문서:link:../2026/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html[우리 첫 채용자: 데이터셋 익명화 도구] * 긴 컨텍스트 LLM 비교 기사 :link:../2026/0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html[DeepSeek-V4-Pro, Kimi K2.6, GLM-5.1] * 백업 에이전트 메커니즘에 관한 기사:link:../2026/0110_mecanisme_backup_contexte_agent_post.html[슬라이딩 윈도우와 한파] ----</code></pre> </div> </div> </div> </div> https://cheroliv.com/blog/pilot-batch/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html Fri, 1 May 2026 00:00:00 +0000 blog/pilot-batch/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_모두를_도망치게_하는_문제">모두를 도망치게 하는 문제</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽는 시간 : 12 minutes</div> <p>나는 LLM을 채용하지 않는다. 나는 익명화자를 채용한다. pgvector RAG를 수행하기 전에, CDA/FPA 전문가를 파인튜닝하기 전에, 클라이언트 워크스페이스를 프로비저닝하기 전에 — 누군가는 데이터의 화장실을 청소해야 한다. 이 직원은 익명화 전문가다 (MVP0, codebase-gradle의 EPIC 2). 그리고 그는 제품이 시장에서 판매 가능하도록 만든다.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">똑</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_모두를_도망치게_하는_문제">모두를 도망치게 하는 문제</h2> <div class="sectionbody"> <div class="paragraph"> <p>훈련 데이터를 다루는 모든 AI 스타트업은 동일한 벽에 부딪힙니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- ---- Données brutes client (SPG, cours, évaluations) ├→ Noms de stagiaires en clair dans les PDF ├→ Emails dans les métadonnées JSON ├→ IP de connexion dans les logs pgvector ├→ Identifiants dans les nœuds Graphify └→ Références OF pilote dans les schémas SQL ---- 결과: RAG를 오염된 데이터에 사용할 경우(개인정보 환각, GDPR 위반, 법적 리스크)가 발생하거나, 아무것도 하지 않을 경우(제품 없음)이 됩니다. 세 번째 방법 — 수동으로 정리하는 것 — 은 확장 가능하지 않다. 내 답변 : 문제를 피하지 마라. L'**자동화하다**. == MVP0 : 익명화 도구, 시험 기간 중 첫 번째로 고용된 MVP0는 기능이 아닙니다. 그것은**편의 전문가**— 더러운, 멍청하고 사악한 일을 하는 직원, 그리고 누구도 피치 덱에서 말하고 싶어 하지 않는. 그가 하는 일: [source] ---- ENTRÉE : Données brutes multi-sources ├→ AsciiDoc (SPG_A2SP.adoc) → noms, dates, OF pilote ├→ JSON (catalogue formations) → emails, téléphones ├→ YAML (config workspace) → tokens OAuth2 ├→ SQL (schémas DDL) → IP, adresses ├→ pgvector (métadonnées embeddings) → identifiants ├→ ONNX (outputs classification) → noms propres └→ Graphify (graph.json) → nœuds avec PII SORTIE : Datasets propres, format standardisé ├→ [ANONYMIZED] remplace les PII détectées ├→ Classification RGPD (niveau 0→4) ├→ Rapport d'audit (quoi a été nettoyé) └→ Dataset prêt pour RAG ET fine-tuning ---- 먼저 가장 명백한 패턴을 감지합니다 (emails`.*@.*`, 토큰`sk-*`, `ghp_*`, IPs), 그 후 그것이 배운다. 수습 기간은 이것이죠 : 우리는 위음성이 통과되지 않는지 확인한 후 그것을 정직원으로 채용합니다. == 이 MVP가 잠금 해제하는 것(그리고 이것이 단순히 규제 준수가 아니다) 익명화는 MVP0가 아니라 GDPR 고속도로 앞의 통행료가 아닙니다. 그것은 고속도로 자체입니다. 다음은 그것이 열어주는 것 : === 현재: 프롬프트의 증강 현실 [source] ---- DONNÉES BRUTES CLIENT ↓ Anonymiseur MVP0 → datasets propres ↓ RAG pgvector (MVP1) → top-K documents similaires (filtrés, anonymisés) ↓ LLM (deepseek-v4-pro) → réponse augmentée, zéro PII ---- RAG는 오염된 데이터에서 검색하지 않는다 — 그것은 공간에서 검색한다**구성으로 깨끗한**. 이것은 답변의 품질에 모든 것을 바꾼다 : LLM은 인식한 PII를 우회하려 시간을 낭비하지 않지만 언급해서는 안 된다. === 미래 : 건강한 데이터에 대한 파인 튜닝 [source] ---- MVP0 → datasets propres accumulés (session après session) ↓ Fine-tuning expert métier (CDA, FPA) sur données zéro PII ↓ Modèle fine-tuné exposé via Ollama (sans fuite de données) ---- 원시 데이터에서의 파인튜닝은 잠재적인 법적 재앙입니다. 깨끗한 데이터에서는 그것은**재현 가능한 방법**. 각 클라이언트는 정제된 데이터셋을 축적하고, 자신의 데이터를 기반하여 비즈니스 전문가를 파인 튜닝할 수 있으며, 개인 데이터를 절대 노출하지 않습니다. == 왜 이것이 시장성이 있나요? 이것은 GDPR 준수 도구가 아닙니다. 이것은**보편적인 문제를 자산으로 바꾸는 재현 가능한 방법**: 1. *모든 교육 기업은 더러운 데이터를 가지고 있습니다* — 이것이 문제입니다 2. *자동화된 다중 소스 정제 파이프라인이 있는 것은 하나도 없습니다* — 이것이 시장입니다 3. *루프: 익명화 → RAG → 파인튜닝은 독점적이다* — 이것이 장벽이다 Edster SaaS (MVP3)는 « Gradle 워크스페이스 »를 판매하지 않을 것입니다. 이 폐쇄 루프를 판매할 것입니다. 그리고 MVP0는 입구입니다. == SQL 형식은 세 번째 컨텍스트 경로 구조화된 데이터 가져오기는 단순히 교환 형식이 아닙니다. SQL 스키마(DDL)는**도메인 엔티티-관계 모델**: [source] ---- CREATE TABLE formation ( id UUID PRIMARY KEY, titre VARCHAR NOT NULL, referentiel RNCP REFERENCES rncp(id), organisme OF REFERENCES of_pilote(id) -- ← va être anonymisé ); ---- 이 DDL은 익명 처리된 후(4줄) LLM의 컨텍스트 소스가 된다. 텍스트가 아니라 — du**비즈니스 모델**. RAG은 내용(벡터 유사도)을 제공하고, Graphify는 관계(정확한 구조)를 제공하며, SQL 스키마는 제공한다**암시적 도메인 주도 설계**: bounded contexts, aggregates, value objects. LLM은 자신의 스키마를 읽음으로써 업계를 이해한다. == 로드맵: MVP0부터 SaaS까지 [source] ---- MVP0 — Anonymiseur (ce que cet article décrit) Sortie : datasets propres, reproductible MVP1 — RAG pgvector (dépend de MVP0) Realité augmentée en prompt sur données nettoyées MVP2 — Graphify + ONNX + SQL DDD (dépend de MVP1) Vecteur composite de contexte (règles + similarité + relations exactes) MVP3 — SaaS Edster (dépend de MVP0-2) Provisionnement workspace client complet ---- 각 MVP는 이전 MVP에 의존합니다. MVP0 없이는 어떤 MVP도 제공할 수 없습니다. 이것이 바로 백로그에서 'P0'가 아닌 이유가 익명화 도구가 아닌 이유이며 — 그것은**MVP0**. 이것은 첫 번째 상업적 산출물이며, 나머지는 그 성공에 달려 있다. == Conclusion : 모든 것을 가능하게 하는 보이지 않는 일 일반적인 스타트업에서는 데이터 정리가 외주화되거나 수작업으로 이루어지거나 간과됩니다. 이 아키텍처에서는 이것이**제품의 핵심**. 익명화하는 사람은 첫 번째 직원이기 때문에, 그에 없이는 아무것도 작동하지 않는다 : * MVP0 없이는 → 법적 RAG이 없습니다 (MVP1) * MVP0 없이는 → 데이터 유출이 없으면 미세 조정도 없습니다 (EPIC 5) * MVP0 없이는 → 신뢰할 수 있는 SaaS 없음 (MVP3) * MVP0 없음 → 프롬프트에서 증강 현실 없음 * MVP0 없음 → 컨텍스트의 세 번째 경로 없음 (SQL DDD) 그는 더러운 일을 한다. 그는 피치에서 결코 언급되지 않을 것이다. 하지만 그가 공장을 움직인다. 그게 바로 우리가 그들을 먼저 고용하는 이유다. == 참고문헌 * 공간적 온톨로지와 신뢰의 원에 관한 기사 :link:../2026/0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html[공간 온톨로지로서의 정렬 메커니즘] * Eager/Lazy 에이전트 거버넌스에 관한 기사 :link:../2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[AsciiDoc을 사용한 AI 에이전트 관리] * Hot/Warm/Cold 메커니즘에 대한 기사 :link:../2026/0110_mecanisme_backup_contexte_agent_post.html[슬라이딩 윈도우와 한파] * 세 개의 LLM 비교에 관한 기사:link:../2026/0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html[DeepSeek-V4-Pro, Kimi K2.6, GLM-5.1] ----</code></pre> </div> </div> </div> </div> https://cheroliv.com/blog/2026/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html Fri, 1 May 2026 00:00:00 +0000 blog/2026/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_모두를_도망치게_하는_문제">모두를 도망치게 하는 문제</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽는 시간 : 12 minutes</div> <p>저는 LLM을 고용하지 않습니다. 저는 익명화자를 고용합니다. RAG pgvector를 수행하기 전, CDA/FPA 전문가를 fine-tuning하기 전, 클라이언트 워크스페이스를 프로비저닝하기 전 — 누군가는 데이터의 화장실을 청소해야 합니다. 그 직원은 익명화 전문가(MVP0, codebase-gradle의 EPIC 2)입니다. 그리고 그가 제품을 시장가능하게 만듭니다.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">틱</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_모두를_도망치게_하는_문제">모두를 도망치게 하는 문제</h2> <div class="sectionbody"> <div class="paragraph"> <p>훈련 데이터를 다루는 모든 인공지능 스타트업은 같은 벽에 부딪힙니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- ---- Données brutes client (SPG, cours, évaluations) ├→ Noms de stagiaires en clair dans les PDF ├→ Emails dans les métadonnées JSON ├→ IP de connexion dans les logs pgvector ├→ Identifiants dans les nœuds Graphify └→ Références OF pilote dans les schémas SQL ---- 결과: 더러운 데이터에서 RAG를 수행한다(개인정보(PII) 환각, GDPR 비준수, 법적 위험)와 그렇지 않으면 아무것도 하지 않는다(제품 없음). 세 번째 방식 — 수작업으로 정리하기 — 는 확장할 수 없다. 내 답변: 문제를 피하지 마라. L'**자동화하다**. == MVP0 : 익명화자, 시험 기간 중 첫 번째 채용 MVP0는 기능이 아닙니다. 그것은**편의 전문가**— 더럽고 멍청하고 사악한 일을 하는 직원, 그리고 누구도 피치 덱에서 이야기하고 싶어하지 않는 사람. 그가 하는 것: [source] ---- ENTRÉE : Données brutes multi-sources ├→ AsciiDoc (SPG_A2SP.adoc) → noms, dates, OF pilote ├→ JSON (catalogue formations) → emails, téléphones ├→ YAML (config workspace) → tokens OAuth2 ├→ SQL (schémas DDL) → IP, adresses ├→ pgvector (métadonnées embeddings) → identifiants ├→ ONNX (outputs classification) → noms propres └→ Graphify (graph.json) → nœuds avec PII SORTIE : Datasets propres, format standardisé ├→ [ANONYMIZED] remplace les PII détectées ├→ Classification RGPD (niveau 0→4) ├→ Rapport d'audit (quoi a été nettoyé) └→ Dataset prêt pour RAG ET fine-tuning ---- 가장 명백한 패턴부터 먼저 감지합니다 (이메일`.*@.*`, 토큰`sk-*`, `ghp_*`, IPs), 그는 배운다. 시험 기간은 이것이죠: 우리는 그가 거짓 음성을 놓치지 않도록 확인한 뒤 그를 정규직으로 채용한다. == 이 MVP가 열어젖히는 것(그리고 이것이 단지 규정이 아님) MVP0 형태의 익명화는 고속도로 앞의 GDPR 통행세가 아니다. 그것은 고속도로 자체이다. 다음은 그것이 열어주는 것: === 현재 : 프롬프트에서의 증강 현실 [source] ---- DONNÉES BRUTES CLIENT ↓ Anonymiseur MVP0 → datasets propres ↓ RAG pgvector (MVP1) → top-K documents similaires (filtrés, anonymisés) ↓ LLM (deepseek-v4-pro) → réponse augmentée, zéro PII ---- RAG은 오염된 데이터에서 검색하지 않고 — 공간에서 검색합니다**구축에 따라 깨끗한**. 이것이 답변 품질의 판도를 바꾼다: LLM은 인식하지만 언급해서는 안 되는 PII를 우회하는 데 시간을 보내지 않는다. === 미래 : 건강한 데이터에 대한 파인튜닝 [source] ---- MVP0 → datasets propres accumulés (session après session) ↓ Fine-tuning expert métier (CDA, FPA) sur données zéro PII ↓ Modèle fine-tuné exposé via Ollama (sans fuite de données) ---- 원시 데이터에서의 파인튜닝은 잠재적인 법적 재앙이다. 깨끗한 데이터에서는 이것이**재현 가능한 방법**. 각 클라이언트는 정제된 데이터셋을 축적하고, 각 클라이언트는 개인 데이터를 노출시키지 않고 자신의 비즈니스 전문가를 자신의 데이터에 대해 미세 조정할 수 있습니다. == 왜 그게 시장성이 있나요? 이건 “GDPR 준수 도구”가 아니에요. 이건**보편적인 문제를 자산으로 바꾸는 재현 가능한 방법** : 1. *모든 교육 기업에는 더러운 데이터가 있습니다* — 이것이 문제입니다 2. *아무것도 자동화된 다중 소스 정제 파이프라인이 없습니다* — 이것이 시장입니다 3. *루프: 익명화 → RAG → 파인튜닝은 전용입니다* — 이것이 장벽이다 SaaS Edster (MVP3)는 « Gradle 워크스페이스 »를 판매하지 않을 것입니다. 그는 이 닫힌 루프를 판매할 것입니다. 그리고 MVP0는 진입점입니다. == SQL 형식은 컨텍스트의 세 번째 방법 구조화된 데이터의 가져오기는 단순히 교환 형식이 아닙니다. SQL 스키마(DDL)는 이를 가지고 있다**도메인 엔티티-관계 모델** : [source] ---- CREATE TABLE formation ( id UUID PRIMARY KEY, titre VARCHAR NOT NULL, referentiel RNCP REFERENCES rncp(id), organisme OF REFERENCES of_pilote(id) -- ← va être anonymisé ); ---- 이 DDL은 한 번 익명 처리된(4번 라인 이후) 후, LLM의 컨텍스트 소스가 됩니다. 텍스트가 아니라 —**비즈니스 모델**. RAG는 내용(유사도 벡터)를 제공합니다, Graphify는 관계(정확한 구조)를 제공합니다, 그리고 SQL 스키마는**암시적 Domain-Driven Design**: bounded contexts, agrégats, value objects. LLM은 자신이 읽은 스키마를 통해 해당 도메인을 이해한다. == 로드맵: MVP0부터 SaaS까지 [source] ---- MVP0 — Anonymiseur (ce que cet article décrit) Sortie : datasets propres, reproductible MVP1 — RAG pgvector (dépend de MVP0) Realité augmentée en prompt sur données nettoyées MVP2 — Graphify + ONNX + SQL DDD (dépend de MVP1) Vecteur composite de contexte (règles + similarité + relations exactes) MVP3 — SaaS Edster (dépend de MVP0-2) Provisionnement workspace client complet ---- 각 MVP는 이전 MVP에 의존합니다. MVP0 없이는 어떠한 MVP도 제공할 수 없습니다. 이것이 백로그에서 익명화자가 « P0 »가 아닌 이유입니다 — 그것은**MVP0**. 이것은 첫 번째 상업적 산출물이자, 나머지는 그것의 성공에 달려 있다. == 결론: 모든 것을 가능하게 하는 보이지 않는 일 일반적인 스타트업에서는 데이터 정리가 외주화되거나, 수작업으로 수행되거나, 간과됩니다. 이 아키텍처에서는 이것이**제품의 핵심**. 익명 처리자는 첫 번째 직원입니다. 그가 없이는 아무것도 작동하지 않기 때문에: * MVP0 없이는 합법적인 RAG이 없습니다 (MVP1) * MVP0 없이는 → 데이터 유출 없이 미세 조정 불가능 (EPIC 5) * MVP0 없이 → 신뢰할 수 있는 SaaS가 없음 (MVP3) * MVP0 없이 → 프롬프트에서의 증강 현실 없음 * MVP0가 없음 → 컨텍스트의 세 번째 방법이 없습니다 (SQL DDD) 그는 더러운 일을 한다. 그는 피치에서 결코 언급되지 않을 것이다. 하지만 그는 공장을 움직이게 하는 사람이다. 그리고 이것이 그가 먼저 고용되는 이유다. == 참고문헌 * 공간 온톨로지와 신뢰의 원에 대한 기사 :link:../2026/0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html[공간 온톨로지, 정렬 메커니즘으로서] * Eager/Lazy 에이전트 거버넌스에 관한 기사 :link:../2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[AsciiDoc을 이용해 AI 에이전트를 운영하다] * 핫/웜/콜드 메커니즘에 관한 기사:link:../2026/0110_mecanisme_backup_contexte_agent_post.html[슬라이딩 윈도우와 차가운 파도] * 세 개의 LLM 비교에 관한 기사 :link:../2026/0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html[DeepSeek-V4-Pro, Kimi K2.6, GLM-5.1] ----</code></pre> </div> </div> </div> </div> https://cheroliv.com/blog/2026/0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html Thu, 30 Apr 2026 00:00:00 +0000 blog/2026/0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_관찰_프롬프트_엔지니어링은_모래성이다">관찰 : 프롬프트 엔지니어링은 모래성이다</a></li> <li><a href="#_네_개의_신뢰_원_공간_온톨로지">네 개의 신뢰 원 : 공간 온톨로지</a> <ul class="sectlevel2"> <li><a href="#_비밀의_정원_cvs_외부_공간">비밀의 정원: CVS 외부 공간</a> <ul class="sectlevel3"> <li><a href="#_gitignore를_거버넌스_구성으로">.gitignore`를 거버넌스 구성으로</a></li> <li><a href="#_스냅샷_메커니즘">스냅샷 메커니즘</a></li> </ul> </li> <li><a href="#_금고_configuration처럼_spring_cloud_config">금고 : `configuration/`처럼 Spring Cloud Config</a></li> <li><a href="#_도서관_office_로_소모성_데이터">도서관: <code>office/</code> 로 소모성 데이터</a></li> <li><a href="#_주물공장_foundry_구현으로">주물공장 : <code>foundry/</code> 구현으로</a></li> </ul> </li> <li><a href="#_procontra_공간_정렬_vs_프롬프트_기반_정렬">Pro/Contra : 공간 정렬 vs 프롬프트 기반 정렬</a> <ul class="sectlevel2"> <li><a href="#_클래식_접근법_사전_프롬프트를_통한_정렬">클래식 접근법: 사전 프롬프트를 통한 정렬</a></li> <li><a href="#_이_접근법_공간_온톨로지_기반_정렬">이 접근법 : 공간 온톨로지 기반 정렬</a></li> </ul> </li> <li><a href="#_워크스페이스의_관계_대수와_델타_옵저버블">워크스페이스의 관계 대수와 델타 옵저버블</a></li> <li><a href="#_컨텍스트_복합_벡터_rag_pgvector_graphify">컨텍스트 복합 벡터 : RAG + pgvector + Graphify</a> <ul class="sectlevel2"> <li><a href="#_컴포넌트_1_rag_langchain4j_postgresql_pgvector">컴포넌트 1 — RAG LangChain4j + PostgreSQL pgvector</a></li> <li><a href="#_구성_요소_2_knowledge_graph_graphify">구성 요소 2 — Knowledge Graph Graphify</a></li> <li><a href="#_구성_요소_3_graphify_증분_희소_집계_가능한_소비_가능한">구성 요소 3 — Graphify 증분 : 희소, 집계 가능한, 소비 가능한</a></li> </ul> </li> <li><a href="#_자동_gdpr_분류_llm은_라우터로_사용">자동 GDPR 분류: LLM은 라우터로 사용</a></li> <li><a href="#_로드맵_asciidoc에서_langgraph4j로">로드맵: AsciiDoc에서 LangGraph4j로</a></li> <li><a href="#_이_아키텍처가_해결하는_것_그리고_해결하지_못하는_것">이 아키텍처가 해결하는 것 (그리고 해결하지 못하는 것)</a></li> <li><a href="#_결론_건축을_담론으로">결론 : 건축을 담론으로</a></li> <li><a href="#_참고문헌">참고문헌</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽는 시간 : 20 minutes</div> <p>프롬프트 엔지니어링은 섬세합니다. 80,000 토큰에서 정렬 규칙은 소음에 묻히고, LLM은 대화 초반에 당신에게 요청한 것을 잊어버립니다. 내 해결책? 텍스트로 정렬하지 말고, 대신<strong>공간</strong>. 나는 개발 워크스페이스를 네 개의 동심 신뢰 원으로 구성했다 — 비밀스러운 내부 정원에서 공개적인 제련소까지 — 그리고 각 원은 파일 시스템의 물리적 영역이다. LLM은 규칙을 상기시킬 필요가 없다; 파일 경로가 그것들을 포함하고 있다. 이것이 어떻게 작동하는지와, 왜 이 공간 기반 정렬 아키텍처가 더 탄력적인지`system prompt`500줄의.</p> </div> <div class="paragraph"> <p>이것은 긴 기사입니다.<br> 편안히 앉아 주세요.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">틱</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_관찰_프롬프트_엔지니어링은_모래성이다">관찰 : 프롬프트 엔지니어링은 모래성이다</h2> <div class="sectionbody"> <div class="paragraph"> <p>3주 동안, Opencode를 사용해 Gradle 플러그인을 개발했으며, 세 가지 다른 LLM — Kimi K2.6, GLM-5.1, 그리고 DeepSeek-V4-Pro (유일한 생존자지만, 이는 또 다른 이야기<a href="0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html">Déjà couverte ici.</a>)를 사용했습니다. 에이전트 거버넌스 방법<a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">Je l’ai documentée en détail dans un précédent article.</a>는 AsciiDoc 파일을 기반으로 합니다 —<code>AGENT.adoc</code>, <code>INDEX.adoc</code>, <code>PROMPT_REPRISE.adoc</code>— 규칙, 백로그, 기록 약 30,000 토큰을 세션 시작 시마다 로드합니다.</p> </div> <div class="paragraph"> <p>그리고 이 문서 인프라스트럭처에도 불구하고, 두 가지 점이 내게 인상적이었지:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>LLM이 잊어버립니다.</strong> EAGER 파일의 각 파일에 절대 규칙을 가지고 있더라도, 누적 토큰이 60,000을 초과하면 (초기 컨텍스트 + 대화), Kimi K2.6은 제안하기 시작했습니다.`Write`구성 파일에 압도적인. GLM-5.1은 Firebase 토큰을 교체해야 할 플레이스홀더와 혼동했다. 규칙은 작성되어 있었지만 — LLM은それを 더 이상 <strong>보지</strong> 못했습니다.</p> </li> <li> <p><strong>거버넌스 자체도 문제가 된다.</strong> Hot/Warm/Cold<a href="0110_mecanisme_backup_contexte_agent_post.html">Article sur la rotation de backup.</a> 메커니즘을 구현한 후, 컨텍스트 폭발을 방지하기 위해 내 EAGER 파일은 여전히 1414줄이었고<a href="0111_audit_contexte_agent_post.html">J’ai documenté cet audit ici.</a> . 거버넌스 — LLM의 과부하를 방지하기 위해 설계되었지만 — LLM을 과부하시켰다.</p> </li> </ol> </div> <div class="paragraph"> <p>프롬프트의 토큰 수에 의존하지 않는 정렬 메커니즘이 필요했습니다.</p> </div> <div class="paragraph"> <p>답변: 텍스트로 정렬하는 것을 멈추고, 로 정렬하기 시작하기<strong>공간</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_네_개의_신뢰_원_공간_온톨로지">네 개의 신뢰 원 : 공간 온톨로지</h2> <div class="sectionbody"> <div class="paragraph"> <p>내 폴더`workspace/<code>(안에</code>~/workspace/`) 이것은 Git 저장소가 아닙니다. 이것은 내가 하는 모든 작업의 근간이다 — 코드, 문서, 교육, 인프라. 그리고 이것은 네 가지 영역으로 구조화되어 있는데, 이 영역들은 정리의 관례가 아니라 하지만 그것들은<strong>동심원 형태의 신뢰</strong></think></p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 6.6666%;"> <col style="width: 13.3333%;"> <col style="width: 20%;"> <col style="width: 26.6666%;"> <col style="width: 33.3335%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">레벨</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">레이블</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">물리적 구역</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">CVS</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">가시성</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>비밀의 정원</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`workspace/`뿌리</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">아무도</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">내면 — 자유로운 생각, 커밋도 없고 발표도 없음</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>금고</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>configuration/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">비공개 Git (혼자)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">비밀, 토큰, 시야 기록. 한 사람만.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>도서관</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>office/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">비공개 Git (확장된)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">교육 데이터, SPG/SPD, JSON 스키마. 신뢰할 수 있는 원이 식별되었습니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>공공 단조소</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>foundry/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Git 공개 (Apache 2.0)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">소스 코드, 플러그인, 테스트, 기술 문서.</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>참고: 테이블에 수준 3이 없습니다. 수준 3은 <strong>전이</strong> 수준이며: 내용의 일부입니다.`office/`익명 처리되어 오픈 데이터로 공개할 준비가 된 상태입니다. 자체적인 물리적 영역이 없으며 — 데이터의 상태일 뿐, 위치가 아닙니다.</p> </div> <div class="paragraph"> <p>각 수준은 구체적인 질문에 답한다 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>아직 공유하기 준비되지 않은 아이디어를 어디에 두어야 할까요? 심지어 제한된 그룹이라도?</strong> → 비밀의 정원. Git 없음. 압력 없음.</p> </li> <li> <p><strong>API 토큰을 어디에 저장해야 유출되지 않을까요?</strong> → 금고 (<code>configuration/</code>) 물리적으로 격리됨. 다른 저장소가 그것을 잘못 참조할 수 없습니다.</p> </li> <li> <p>어디서 파일럿 OF와 함께 교육 카탈로그를 구축할 수 있나요?<code>office/</code>). 버전 관리된, 협업 가능한, 하지만 비공개인.</p> </li> <li> <p>오픈소스 Gradle 플러그인을 어디에서 산업화할 수 있나요?<code>foundry/</code>). 공개, 포크 가능, CI에서 테스트됨.</p> </li> </ul> </div> <div class="paragraph"> <p>이 온톨로지는<strong>LLM에 의해 소비 가능한</strong>. 파일을 읽을 때`foundry/plantuml-gradle/src/`, 그는 암시적으로 알고 있다 : "나는 4번째 원 안에 있다 — 공개 코드, 필수 테스트, 비밀 없음, 교육 데이터 없음". 그는 그것을 상기시켜줄 프롬프트가 필요하지 않다.</p> </div> <div class="sect2"> <h3 id="_비밀의_정원_cvs_외부_공간">비밀의 정원: CVS 외부 공간</h3> <div class="paragraph"> <p>이것은 가장 중요한 개념 — 그리고 가장 직관에 어긋나는 개념입니다.</p> </div> <div class="paragraph"> <p>뿌리`workspace/<code>없습니다</code>.git/<code>. 거이에 존재하는 문서들 (`WORKSPACE_VISION.adoc</code>, <code>WORKSPACE_AS_PRODUCT.adoc</code>, <code>WORKSPACE_ORGANIZATION.adoc</code>— 그리고 지금 당신이 읽고 있는 것, 그것에서 비롯된 것) 은 버전 관리, 공유, 혹은 심지어 나 이외의 다른 사람이 다시 읽는 것을 목적으로 하지 않습니다. 이것들은<strong>발아 중인 생각들</strong>.</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>비밀의 정원은 본래적으로 *out-of-CVS*입니다. 버전 관리가 없는 것은 생각하는 자유의 조건이다. 거기에서 쓰는 것은 읽히기 위한 것이 아니라 — 거기에서 쓰는 것은 자신의 관점을 명확히 하기 위한 것이다.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>하지만 이 자유에는 비용이 따른다: 하나`rm`우발적인 것이고, 이는 전략적 사고의 몇 달이 사라지는 것을 의미합니다. 해결책은 정원을 버전 관리하는 것이 아닙니다(그것을 파괴할 뿐입니다) — 그것은 그것을 하는 것<strong>반사하다</strong>가장 좁은 원 안에서.</p> </div> <div class="sect3"> <h4 id="_gitignore를_거버넌스_구성으로">.gitignore`를 거버넌스 구성으로</h4> <div class="paragraph"> <p>의 근원에서`workspace/<code>, 하나의 파일</code>.gitignore`미니멀은 선언한다<strong>히스토리화 정책</strong>비밀 정원의 파일들:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">.goosehints .goose</code></pre> </div> </div> <div class="paragraph"> <p>Ce <code>.gitignore`일반적인 Git 기능이 없습니다 ( 없습니다</code>.git/`루트에서). 그것은 ~처럼 작용한다<strong>거버넌스 구성 파일</strong>특정 질문에 답하는 : <strong>비밀 정원의 어떤 유물들이 역사화되어야 하고, 어떤 것들은 순전히 일시적인 것인가?</strong></p> </div> <div class="ulist"> <ul> <li> <p>목록에 나열된 파일들`.gitignore`—<code>.goosehints</code>, <code>.goose</code>— 에이전트가 생성한 일시적인 유물입니다. 전략적 가치가 없습니다. 히스토리화가 없습니다.</p> </li> <li> <p>파일들`.adoc`뿌리의 —<code>WORKSPACE_VISION.adoc</code>, <code>WORKSPACE_ORGANIZATION.adoc</code>, <code>WORKSPACE_AS_PRODUCT.adoc</code>, <code>WHAT_THE_GAMES_BEEN_MISSING.adoc</code>, <code>depots_implementes_strategie.adoc</code>, <code>synthese-LLMs-long-contexte.adoc</code>— 아닙니다<strong>안</strong>안에`.gitignore`. 이것은 역사화해야 할 유물들입니다.</p> </li> </ul> </div> <div class="paragraph"> <p>Le `.gitignore`은/는<strong>거버넌스 스키마</strong>: 여기에 나열되지 않은 모든 것은 스냅샷 후보가 됩니다. 그리고 LLM은 이 파일을 읽면서 정확히 무엇이 아카이브되어야 하고 무엇이 무시될 수 있는지를 알고 — 프롬프트에서 이를 상기시킬 필요가 없습니다.</p> </div> </div> <div class="sect3"> <h4 id="_스냅샷_메커니즘">스냅샷 메커니즘</h4> <div class="paragraph"> <p>만들었습니다`configuration/vision-archive/<code>: 모든 것의 날짜가 있는 스냅샷</code>.adoc`루트에서, 개인 저장소에 커밋됨`configuration/`. 각 브레인스토밍 세션은 스냅샷을 생성합니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">DATE=$(date +%Y-%m-%d) mkdir -p /home/cheroliv/workspace/configuration/vision-archive/$DATE cp /home/cheroliv/workspace/*.adoc /home/cheroliv/workspace/configuration/vision-archive/$DATE/ cd /home/cheroliv/workspace/configuration && git add vision-archive/ && \ git commit -m "vision-archive: snapshot $DATE"</code></pre> </div> </div> <div class="paragraph"> <p>절차는 세션 종료 시 LLM 자체에 의해 트리거되며, 이 LLM이 전체 라우팅 작업을 수행합니다. 각 스냅샷은 시간 T에서 전략적 사고의 전체 상태를 캡처합니다.</p> </div> <div class="paragraph"> <p>의 Git 기록`configuration/`되는<strong>나의 전략적 사고의 전기</strong>. 저는 만들 수 있는`git log — vision-archive/`그리고 내 시력의 변화를 세션별로, 날짜별로 보다.</p> </div> <div class="paragraph"> <p>업무 하루 후 실제 히스토리 예시 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">$ git -C configuration log --oneline -- vision-archive/ 1089d1b vision-archive: fin de session finale 2026-05-03 6b21eaf vision-archive: fin de session 2026-05-03-1300 1690f82 vision-archive: post-article 2026-05-03 28e6593 vision-archive: post-migration 2026-05-03 3707b78 vision-archive: snapshot 2026-05-03 — jardin secret initial</code></pre> </div> </div> <div class="paragraph"> <p>하루에 다섯 개의 스냅샷이 있다. 각각은 복구 지점이다. 각각은 전략의 발생에서 이정표이다.</p> </div> <div class="paragraph"> <p>폴더`configuration/vision-archive/latest/`항상 포함하고 있는<strong>작업 사본</strong>마지막 스냅샷의, 빠른 참조를 제공하여 Git 기록을 탐색할 필요가 없습니다.</p> </div> <div class="paragraph"> <p>그리고 LLM에 대해, 그것은<strong>일관성 오라클</strong>: 그가 모순을 관찰할 때, 현재 구현과 과거 날짜에 보관된 비전 사이에서 이를 발견하면, 그는 이를 보고할 수 있다.</p> </div> </div> </div> <div class="sect2"> <h3 id="_금고_configuration처럼_spring_cloud_config">금고 : `configuration/`처럼 Spring Cloud Config</h3> <div class="paragraph"> <p>`configuration/`시각의 아카이브만을 포함하지 않는다. 그 주요한 — 그리고 미래의 — 기능은 되는 것이다.<strong>Spring Cloud Config 서버</strong>. 모든 비밀, 토큰, 자격 증명, 인프라 디스크립터는 여기, 단독 소유자에게만 접근 가능한 비공개 Git 리포지토리 내에 있습니다.</p> </div> <div class="paragraph"> <p>왜 별도의 저장소가 아니라 파일을 사용하나요?`.env`각 프로젝트에서?</p> </div> <div class="ulist"> <ul> <li> <p><strong>의도치 않은 비밀 푸시</strong> : 불가능합니다. 비밀은 공개 프로젝트가 실수로 참조할 수 없는 비공개 리포지토리에 저장됩니다.</p> </li> <li> <p><strong>감사</strong> : Git 기록은 각 구성 변경의 이력을 제공합니다. 누가 무엇을 바꾸었는지, 언제였는지, 어떤 SHA 해시였는지.</p> </li> <li> <p><strong>롤백</strong> :`git revert`손상된 구성에 대해. 스냅샷, 수동 백업 없음.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_도서관_office_로_소모성_데이터">도서관: <code>office/</code> 로 소모성 데이터</h3> <div class="paragraph"> <p>`office/`블로그 글, 기술 사양, 교육 자료(38개의 FPA, SPG/SPD 강의 디렉터리, JSON 스키마, Bloom/Harrow/Krathwohl 분류체계)를 포함하며 — 이를 구성하는 모든 것<strong>교육 자료</strong>.</p> </div> <div class="paragraph"> <p>하지만`office/`그 문서 서랍만이 아닙니다. 그것은<strong>구조화된 데이터 소스</strong>그 Gradle 플러그인들이`foundry/`소비한다. 하나의 블로그 글 안에서`office/`는 플러그인이 HTML로 변환할 입력입니다. AsciiDoc SPG 안에`office/metiers/FPA/`는 오케스트레이터가 파싱하여 슬라이드, 퀴즈, 비디오 캡슐을 생성하는 아티팩트입니다.</p> </div> <div class="paragraph"> <p>Et le `build.gradle.kts`의 근본에서`office/`비즈니스 코드가 아닙니다 — 그것은<strong>플러그인 에코시스템의 소비 스크립트</strong>. 그는 말합니다: "다음은 내가 사용하는 Gradle 플러그인이고 이것은 내 워크스페이스의 컨텍스트입니다</p> </div> </div> <div class="sect2"> <h3 id="_주물공장_foundry_구현으로">주물공장 : <code>foundry/</code> 구현으로</h3> <div class="paragraph"> <p><code>foundry/`이 포함된<strong>산업화된 코드</strong>. 54 Git 저장소, 중 7개는 현재 에 의해 관리되고 있는</code>.agents/`. 여기서 비전이 실행 가능해집니다 — Gradle 플러그인, CI/CD, JUnit5 + Cucumber 테스트.</p> </div> <div class="paragraph"> <p>관계와`office/`양방향입니다:</p> </div> <div class="ulist"> <ul> <li> <p><code>office/</code>→`foundry/`교육 데이터는 플러그인이 소비하는 원료이다.</p> </li> <li> <p><code>foundry/</code>→<code>office/</code>: 플러그인은 데이터를 생산해 풍부하게 만든다`office/` — le `graph.json`graphify-gradle, 컴파일된 슬라이더 데크, 빌드 보고서.</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_procontra_공간_정렬_vs_프롬프트_기반_정렬">Pro/Contra : 공간 정렬 vs 프롬프트 기반 정렬</h2> <div class="sectionbody"> <div class="paragraph"> <p>두 가지 접근 방식을 비교해 봅시다.</p> </div> <div class="sect2"> <h3 id="_클래식_접근법_사전_프롬프트를_통한_정렬">클래식 접근법: 사전 프롬프트를 통한 정렬</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 20%;"> <col style="width: 80%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ 프로</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌ 반대</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">구현하기 간단합니다. 시스템 프롬프트 내의 텍스트 블록.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>장문 컨텍스트에 취약함</strong> : 규칙은 80K 토큰 이후에 묻힙니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">일반적인 규칙(톤, 형식)에 적용됩니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>검증할 수 없는</strong> : 아무것도 LLM이 규칙을 위반하는 것을 막지 못한다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">프로젝트 아키텍처를 재고할 필요가 없습니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>양도 불가</strong> : 각 repo가 규칙을 재정의합니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>순전히 선언적</strong> : LLM은 그것이 *해야 할 것*임을 알지만, 아무것도それを 막지 못한다.</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_이_접근법_공간_온톨로지_기반_정렬">이 접근법 : 공간 온톨로지 기반 정렬</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 20%;"> <col style="width: 80%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ 프로</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌ 반대</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>장문 컨텍스트에 탄력적</strong> : 규칙은 파일 경로에 있으며, 먼 프롬프트에 있지 않습니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>초기 인프라 비용</strong> : 작업 영역을 원형으로 구성하는 데 시간이 걸립니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>기계적으로 검증 가능한</strong> : 비밀이 있는`foundry/<code>탐지할 수 있는`git check-ignore</code>.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>필요한 규율</strong> : 새로운 기여자는 원을 이해해야 한다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>양도 가능한</strong> : 하나`AGENT.adoc`표준은 모든 새 프로젝트에 대해 원을 노출합니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>공간 제약 조건만 다룹니다</strong> — 코드 스타일은 프롬프트에 유지됩니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>설계부터 보안</strong> : 하나`git push`부터`foundry/<code>전시할 수 없습니다`configuration/</code>.</p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>비LLM 에이전트에서 소비 가능</strong> : Gradle 오케스트레이터는 원에 따라 라우팅할 수 있다.</p></td> <td class="tableblock halign-left valign-top"></td> </tr> </tbody> </table> <div class="paragraph"> <p>주요 이점은 방어적인 것이 아닙니다(보안, 가시성) — 그것은<strong>창의적인</strong>. LLM이 온톨로지에 의해 구조화된 공간에서 작업할 때, 그것은 어떤 프롬프트도 허용하지 않는 것을 수행할 수 있다: <strong>델타를 관찰한다</strong></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_워크스페이스의_관계_대수와_델타_옵저버블">워크스페이스의 관계 대수와 델타 옵저버블</h2> <div class="sectionbody"> <div class="paragraph"> <p>LLM이 순회할 때`foundry/<code>, 그것은 가지고 있다<strong>구조화된 데이터 격자</strong>: 노드 (플러그인, 파일, 테스트, 의존성), 타입이 지정된 엣지 (`import</code>, <code>depends_on</code>, <code>generates</code>, <code>tests</code>), 구성 및 순서 관계 (`training-gradle`저장소를 추출`slider-gradle`슬라이드를 생성한다 →`capsule-gradle`비디오를 올려)</p> </div> <div class="paragraph"> <p>이 대수학은 어디서도 명문화되어 있지 않다 — 그러나 그것은 <strong>관찰 가능하다</strong>. 각`build.gradle.kts`종속성을 노출합니다. 각`INDEX.adoc`교차 참조를 보여줍니다.</p> </div> <div class="paragraph"> <p>LLM은 이 대수학을 관찰하고 이를 감지합니다<strong>델타</strong>: 시스템이 이미 생산할 수 있는 것과 비전이 설명하는 것 사이의 차이.</p> </div> <div class="paragraph"> <p>이 델타부터, 그는 일부를 정의할 수 있다<strong>전문가들의 비즈니스 지도</strong>— CDA (응용 프로그램 설계·개발자, Kotlin/Gradle/JHipster) 그리고 FPA (성인 전문 강사, 교수법/Qualiopi/Bloom) — 그리고 각 전문가에게 부족한 점을 식별하다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">Expert CDA (Kotlin/Gradle/JHipster) ├── Plugins : jhipster-gradle-plugins, plantuml-gradle, │ codebase-gradle ├── Delta : pas encore de SPG CDA formalisé, │ pas de fine-tuning expert CDA Expert FPA (Pédagogie/Qualiopi/Bloom) ├── Plugins : training-gradle, slider-gradle, │ school-backoffice/forms, capsule-gradle ├── Matériel : 38 modules cours, SPG/SPD, taxonomies └── Delta : parser AsciiDoc→JSON à créer, orchestrateur à coder</code></pre> </div> </div> <div class="paragraph"> <p>LLM은 무엇을 해야 할지 알려줄 필요가 없습니다. 델타는 구조에서 발생합니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_컨텍스트_복합_벡터_rag_pgvector_graphify">컨텍스트 복합 벡터 : RAG + pgvector + Graphify</h2> <div class="sectionbody"> <div class="paragraph"> <p>관계 대수는 이론적 구성이 아닙니다. 그녀는 세 가지 구성 요소에 의해 *구체화*되며, 하나를 형성합니다<strong>컨텍스트 복합 벡터</strong>LLM을 위해.</p> </div> <div class="sect2"> <h3 id="_컴포넌트_1_rag_langchain4j_postgresql_pgvector">컴포넌트 1 — RAG LangChain4j + PostgreSQL pgvector</h3> <div class="paragraph"> <p>저는 이미 LangChain4j를 두 개의 플러그인에서 프로덕션 환경에 사용하고 있습니다:`slider-gradle`(4 providers LLM)와`plantuml-gradle`(7개의 제공자). ONNX 임베딩 (AllMiniLmL6V2)은 데이터의 색인을 생성합니다`office/`그리고 소스 코드`foundry/`PostgreSQL + pgvector에서</p> </div> <div class="paragraph"> <p>이 RAG는 두 차원에서 동작합니다 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Dimension data</strong> : 문서들`office/`(SPG, 문서, 교육, JSON 스키마)</p> </li> <li> <p><strong>Dimension 코드</strong> : 코드베이스`foundry/`(소스 Kotlin, 테스트 Cucumber, AGENT.adoc)</p> </li> </ul> </div> <div class="paragraph"> <p>Intersection은 <strong>무엇</strong> (비즈니스 도메인)와 <strong>어떻게</strong> (구현)를 모두 포함합니다.</p> </div> </div> <div class="sect2"> <h3 id="_구성_요소_2_knowledge_graph_graphify">구성 요소 2 — Knowledge Graph Graphify</h3> <div class="paragraph"> <p>Graphify가 통합되어 있습니다`plantuml-gradle`(109 테스트, 380/380 PASS)를 생성한다`graph.json`— 구조화된 knowledge graph, 노드, 엣지, 그리고 자동으로 감지된 커뮤니티가 있는</p> </div> <div class="paragraph"> <p>RAG은 벡터 유사성(흐림)으로 작동하는 반면, 지식 그래프는 …​로 작동한다.<strong>정확한 관계</strong>(결정론적):`graphify query`의미적인 질문에 대해 (~50 토큰),`graphify path`탐색하기 위해,`graphify explain`설명하기 위해.</p> </div> </div> <div class="sect2"> <h3 id="_구성_요소_3_graphify_증분_희소_집계_가능한_소비_가능한">구성 요소 3 — Graphify 증분 : 희소, 집계 가능한, 소비 가능한</h3> <div class="paragraph"> <p>이것이 핵심적인 건축 결정입니다.</p> </div> <div class="paragraph"> <p>Graphify는 단일 저장소에 살면 안 됩니다. 그것은 방식으로 살아야 합니다.<strong>흩어진</strong>각 플러그인에서:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>*각 플러그인*은 Gradle 작업을 포함합니다`updateKnowledgeGraph`Graphify를 호출하는<strong>스코프 자체에서</strong>그리고 하나 생산한다`graph.json`현지의.</p> </li> <li> <p>* 빌드 스크립트의`office/<code>* 소비한다`graphify-gradle`와/과`rootDir = /home/cheroliv/workspace`그리고 하나를 생산한다`graph.json</code> <strong>전역</strong>로컬 그래프를 집계합니다.</p> </li> <li> <p><strong>각 플러그인의 RAG</strong> 을 주입합니다`graph.json`글로벌처럼<strong>컨텍스트 필터</strong>LLM 쿼리용.</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">TÂCHE GRADLE (dans chaque plugin) ↓ graphify → graph.json (scope local) ↓ office/build.gradle.kts → graph.json (scope global) ↓ RAG pgvector (dans slider, plantuml, codebase...) ↓ ← injection du graph.json comme filtre LLM (deepseek-v4-pro) ↓ ← observation algèbre relationnelle ↓ ← détection delta vs cartographies experts PRIORISATION → prochaine tâche</code></pre> </div> </div> <div class="paragraph"> <p>결과 : LLM은 빈 공간을 찾지 않고 — 지식 그래프에 구조화된 공간을 탐색한다. "다이어그램 생성"에 대한 쿼리는 그래프의 관련 노드에 도달할 수 있다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_자동_gdpr_분류_llm은_라우터로_사용">자동 GDPR 분류: LLM은 라우터로 사용</h2> <div class="sectionbody"> <div class="paragraph"> <p>공간 온톨로지는 LLM을 맞추는 데 만족하지 않고 — 그에게 하나를 준다<strong>RGPD 분류 표</strong>각 데이터를 그 합법적인 영역으로 라우팅하기 위해.</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 12.5%;"> <col style="width: 37.5%;"> <col style="width: 25%;"> <col style="width: 25%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">기준</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">LLM 탐지</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">행동</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">최대 레벨</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">개인정보 (이름, 이메일, IP)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">패턴`@`, IP, 고유명사</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">익명화하다 →`[OF_PILOTE]`또는 라우터 레벨 2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">토큰 / 비밀 / 자격 증명</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">패턴`sk-…​<code>, `ghp_…​</code>, <code>ya29…​</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">라우터 →<code>configuration/</code>. 에 의해 참조된`${VAR}`코드 안에.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">내부 URL</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">포함한다`localhost`, 사설 IP</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">익명화 →<code>${API_URL}</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">교육 데이터 (SPG, 수업)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">구조 Bloom/Qualiopi</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">라우터 →<code>office/</code>(레벨 2). 내보내기 시 더블 버전</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">소스 코드 / 테스트</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">확장`.kt`, <code>.kts`안에`foundry/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">라우터 →`foundry/`비밀이 없는지 확인합니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>세션이 끝날 때, LLM은 하나를 실행합니다<strong>전체 작업</strong>:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>읽기의`.gitignore`임시 아티팩트를 식별하기 위한 기준 (스냅샷에서 제외) vs 전략적 아티팩트 (히스토리화)</p> </li> <li> <p>모든 파일의 인벤토리`.adoc`뿌리의`workspace/`</p> </li> <li> <p>필터링: 나열된 파일 제외`.gitignore`, 모든 다른 것들의 포함</p> </li> <li> <p>복사 안에`configuration/vision-archive/$DATE/<code>와 심볼릭 링크 업데이트`latest/</code></p> </li> <li> <p>커밋이 저장소에 있습니다`configuration/`구조화된 메시지와 함께</p> </li> <li> <p>각 수정된 파일에 대한 자동 GDPR 분류 (모든 원)</p> </li> <li> <p>라우팅 : 데이터`office/<code>→ 개인 커밋, 코드`foundry/</code>→<code>./gradlew check</code>, 설정 → 커밋</p> </li> <li> <p>GDPR 경보와 보관 확인이 포함된 구조화된 보고서</p> </li> </ol> </div> <div class="paragraph"> <p>Le `.gitignore`루트는 Git 구성 파일이 아닙니다 — 그것이<strong>히스토리 관리를 위한 거버넌스 파일</strong>. 그는 LLM이 소비하는 스키마를 정의하여, 전략적 전기에 들어갈 비밀 정원의 파일들과 버릴 수 있는 파일들을 결정한다.</p> </div> <div class="paragraph"> <p>LLM은 더 이상 단순한 텍스트 생성기가 아닙니다. 그것은<strong>정보 관리자</strong>생태계의 — 생산자, 분류자, 라우터.</p> </div> </div> </div> <div class="sect1"> <h2 id="_로드맵_asciidoc에서_langgraph4j로">로드맵: AsciiDoc에서 LangGraph4j로</h2> <div class="sectionbody"> <div class="paragraph"> <p>오늘날, 이 거버넌스는 <strong>결정론적</strong> : LLM은 AsciiDoc 파일에 설명된 절차를 적용합니다. 이것은<strong>1단계</strong>— LLM 메모리를 사용한 프롬프트 엔지니어링.</p> </div> <div class="paragraph"> <p>La <strong>단계 2</strong>각 단계의 절차를 추출하여<strong>타입이 지정된 Gradle 작업</strong>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">./gradlew endSessionWorkspace → snapshot vision-archive ./gradlew endSessionProject → archive .agents/ ./gradlew endSessionReport → rapport multi-zones</code></pre> </div> </div> <div class="paragraph"> <p>La <strong>3단계</strong>세션 종료 과정을 하나의 모델링할 것이다.<strong>상태 그래프</strong>와https://github.com/langgraph4j/langgraph4j[LangGraph4j] :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">[Start] → [Inventaire fichiers modifiés] → [Classification RGPD] (nœud ONNX) → [Branchement par cercle] ├→ cercle 0 → snapshot → commit ├→ cercle 2 → anonymisation → commit ├→ cercle 4 → archive → commit └→ cercle 1 → commit configuration/ → [Rapport] → [End]</code></pre> </div> </div> <div class="paragraph"> <p>이 그래프는 CI/CD에서 버전 관리되고, Gradle에 의해 실행되며, 플러그인의 GitHub Secrets를 통해 구성됩니다. LLM은 더 이상 라우팅을 결정할 필요가 없습니다 — 그래프가 이를 처리할 것입니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_이_아키텍처가_해결하는_것_그리고_해결하지_못하는_것">이 아키텍처가 해결하는 것 (그리고 해결하지 못하는 것)</h2> <div class="sectionbody"> <div class="admonitionblock caution"> <table> <tr> <td class="icon"> <i class="fa icon-caution" title="🔒"></i> </td> <td class="content"> <div class="paragraph"> <p>공간 온톨로지는 모든 것을 다루지 않습니다. 코드 스타일 규칙, 명명, 아키텍처 디자인 선택 — 모든 것이 프롬프트에 남아 있습니다. 공간 온톨로지가 해결하는 것은<strong>보안 및 가시성 계층</strong>: 각 바이트가 살아야 하는 곳, 그리고 그것을 볼 수 있는 자.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>그녀가 구체적으로 제공하는 것은 다음과 같습니다:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>없습니다`git push`우발적인 비밀</strong> : 비밀들은 안에 있다`configuration/<code>(cercle 1). 공공 프로젝트는 안에`foundry/</code>(원 4). 두 곳을 모두 지나는 경로는 없습니다.</p> </li> <li> <p><strong>데이터에 비즈니스 코드가 없습니다</strong> :`office/<code>포함하는</code>.adoc`, YAML, JSON 스키마—그러나`.kt`. Le `build.gradle.kts`거기 사는 사람은 소비 스크립트이지, 업무 코드가 아닙니다.</p> </li> <li> <p><strong>전략적 사고가 드러나지 않음</strong> : 비전 문서들은 비밀 정원에 거주합니다 (CVS 외 루트). 스냅샷은`configuration/`(개인 금고). 신뢰 범위가 확장된 경우에도 아무도 전략의 기원을 읽지 않는다.</p> </li> <li> <p><strong>자동 우선순위 지정</strong> : LLM은 관계 대수(존재하는 것)와 전문가 매핑(필요한 것) 사이의 델타를 관찰합니다. 다음 개발 작업은 이 델타에서 발생합니다.</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_결론_건축을_담론으로">결론 : 건축을 담론으로</h2> <div class="sectionbody"> <div class="paragraph"> <p>나는 내 사이트의 footer에 정치적 선언문을 넣지 않는다. 나는 내 프롬프트에 윤리적 규칙을 넣지 않는다. 정렬은 텍스트에 있지 않다 — 그것은 안에 있다<strong>파일 시스템</strong>.</p> </div> <div class="paragraph"> <p>LLM이 이 공간에서 작업할 때는 비밀을 유출할 수 없습니다(경로가 이를 막기 때문입니다). 교육 데이터와 소스 코드를 혼동할 수 없습니다(물리적 영역이 다르기 때문입니다). 80,000 토큰의 보안 규칙을 잊을 수 없습니다—규칙이 프롬프트에 있지 않고 ___에 있습니다.<code>workspace/</code>→<code>configuration/</code>→<code>office/</code>→`foundry/`각 파일 읽기마다 반응적입니다.</p> </div> <div class="paragraph"> <p>이것은 에이전트 정렬에 적용된 <strong>secure by design</strong> 원칙이다: LLM에게 규칙을 기억하도록 요구하지 말고, 아키텍처가 오류를 구조적으로 불가능하게 만들도록 하라.</p> </div> <div class="paragraph"> <p>그 사이에, 그것은 프롬프트가 LLM에게 줄 수 없는 것을 LLM에게 줍니다: 능력을<strong>인식하다</strong>그가 어디에 있는지, 무엇이 존재하는지, 무엇이 부족한지 — 그로부터 그가 해야 할 일을 추론하다</p> </div> </div> </div> <div class="sect1"> <h2 id="_참고문헌">참고문헌</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Eager/Lazy 에이전트 거버넌스에 관한 기사 :<a href="../2026/0108_gouvernance_agent_opencode_eager_lazy_post.html">AsciiDoc으로 AI 에이전트 관리하기</a></p> </li> <li> <p>Hot/Warm/Cold 메커니즘에 대한 기사 :<a href="../2026/0110_mecanisme_backup_contexte_agent_post.html">슬라이딩 윈도우와 한파</a></p> </li> <li> <p>컨텍스트 감사에 관한 기사 :<a href="../2026/0111_audit_contexte_agent_post.html">당신만의 지배구조가 문제가 될 때</a></p> </li> <li> <p>세 가지 LLMs 비교 글 :<a href="../2026/0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html">DeepSeek-V4-Pro, Kimi K2.6, GLM-5.1</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0113_integration_firebase_contact_form_post.html Wed, 29 Apr 2026 00:00:00 +0000 blog/2026/0113_integration_firebase_contact_form_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_장면_아무것도_저장하지_않는_폼">장면: 아무것도 저장하지 않는 폼</a> <ul class="sectlevel2"> <li><a href="#_supabase의_유산">Supabase의 유산</a></li> <li><a href="#_유령_이중_제출">유령 이중 제출</a></li> </ul> </li> <li><a href="#_왜_firebase가_supabase_대신인가">왜 Firebase가 Supabase 대신인가?</a></li> <li><a href="#_1단계_firebase_프로젝트_만들기">1단계: Firebase 프로젝트 만들기</a> <ul class="sectlevel2"> <li><a href="#_초기화">초기화</a></li> <li><a href="#_firestore_보안_규칙">Firestore 보안 규칙</a></li> </ul> </li> <li><a href="#_phase_2_제출_javascript_다시_쓰기">Phase 2 : 제출 JavaScript 다시 쓰기</a> <ul class="sectlevel2"> <li><a href="#_의존성_window_firebase">의존성 `window.<em>FIREBASE</em></a></li> <li><a href="#_새로운_contact_js">새로운 `contact.js</a></li> </ul> </li> <li><a href="#_3단계_supabase의_죽은_코드_정리">3단계: Supabase의 죽은 코드 정리</a></li> <li><a href="#_단계_4_푸터_구성">단계 4: 푸터 구성</a></li> <li><a href="#_phase_5_최종_아키텍처">Phase 5 : 최종 아키텍처</a></li> <li><a href="#_이_이동이_도그푸딩에_대해_말하는_것">이 이동이 도그푸딩에 대해 말하는 것</a> <ul class="sectlevel2"> <li><a href="#_수정_사항_요약">수정 사항 요약</a></li> </ul> </li> <li><a href="#_다음_단계_백로그">다음 단계 (백로그)</a></li> <li><a href="#_참고문헌">참고문헌</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽기 시간 : 12 minutes</div> <p>개월 동안, 이 사이트의 연락처 양식은 모의 JavaScript에서 작동했습니다 — 85% 성공을 약속하는, 가짜 Firestore, 저장된 데이터가 전혀 없었습니다. 초기 계획은 이메일 알림을 위한 Google Apps Script와 함께 Supabase 백엔드를 사용하는 것이었습니다. 포기되었습니다. 오늘, 저는 Firebase Firestore로의 마이그레이션에 대해 이야기합니다: 프로젝트 생성, 보안 규칙, JS 재작성, Supabase 죽은 코드 정리. 그리고 왜 이 선택이 개발 철학에 대해 더 넓은 무언가를 말하는지.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">틱</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_장면_아무것도_저장하지_않는_폼">장면: 아무것도 저장하지 않는 폼</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 사이트는 JBake로 생성된 내 Gradle 플러그인입니다.<code>bakery</code>. 그것은 100% 정적입니다 — 백엔드도 없고 데이터베이스도 없습니다. 그런데 저는 연락처 폼이 있습니다. 페이지`contact.html`있어요, HTML이 준비되었습니다(이름, 이메일, 전화번호, 제목, 메시지, HTML5 검증, 스팸 방지 하니팟 필드), Bootstrap 스타일이 적용되었습니다. 시각적으로 모든 것이 완벽합니다.</p> </div> <div class="paragraph"> <p>제출했을 때엔 아무것도 일어나지 않아요.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">const firebaseMock = new Promise((resolve, reject) => { setTimeout(() => { if (Math.random() < 0.85) { resolve({ status: 201, message: 'Message stored in Firestore.' }); } else { reject({ status: 500, message: 'Firestore write failed.' }); } }, 1500); });</code></pre> </div> </div> <div class="paragraph"> <p>모의. 가짜 약속. 사용자는 스피너를 보고, 이어서 '메시지가 성공적으로 전송되었습니다!' 라는 메시지를 봅니다. 하지만 데이터는 허공으로 사라집니다. 어디에도 메시지가 저장되지 않습니다.</p> </div> <div class="paragraph"> <p>상황은 깨진 양식보다 더 나빠 — 그것은 거짓말을 하는 양식이다.</p> </div> <div class="sect2"> <h3 id="_supabase의_유산">Supabase의 유산</h3> <div class="paragraph"> <p>초기 계획은, …​에 문서화된`content/draft/integration_formulaire_contact_supabase.adoc`, 예정하고 있었다 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>테이블이 있는 Supabase 데이터베이스`contacts`와 Row Level Security</p> </li> <li> <p>한 RPC`handle_contact_form`서버 측</p> </li> <li> <p>Google Apps Script 웹훅을 호출하는 SQL 트리거</p> </li> <li> <p>Gmail 알림 메일을 보내는 Google Apps Script</p> </li> </ol> </div> <div class="paragraph"> <p>해당 JavaScript 코드는 여전히 존재합니다 안에`script.js`. 반이 있다`SupabaseManager`전역 변수를 이용해 Supabase 클라이언트를 초기화하는`SUPABASE_URL` et <code>SUPABASE_KEY</code>, 그리고 한 클래스`ContactFormHandler`폼의 submit 이벤트를 듣고 호출한다`SupabaseManager.submitContactForm()`.</p> </div> <div class="paragraph"> <p>문제 : 이 전역 변수들은 더 이상 푸터에 주입되지 않습니다. 그`<script src="supabase-js">`제거되었습니다. 코드가 호출합니다.`supabase.createClient()`변수에서`supabase`더 이상 존재하지 않습니다. 그래서:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">console.error : 'Supabase client library (supabase-js) is not loaded.'</code></pre> </div> </div> <div class="paragraph"> <p>데이터가 저장되지 않을 뿐만 아니라 제출 코드도 죽었습니다.</p> </div> </div> <div class="sect2"> <h3 id="_유령_이중_제출">유령 이중 제출</h3> <div class="paragraph"> <p>일을 더 악화시키기 위해, 하나가 있습니다.<strong>침묵적인 경쟁</strong>같은 폼 위의 두 핸들러 사이 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>`contact.js`제출을 듣고, Firebase 모의 객체를 호출해</p> </li> <li> <p><code>script.js</code>— 경유`ContactFormHandler`— 또한 제출을 들어라, 호출해`SupabaseManager`</p> </li> </ol> </div> <div class="paragraph"> <p>둘 다 한다`event.preventDefault() + event.stopPropagation()<code>.처럼`contact.js`먼저 로드됩니다`footer.thyme</code>, 그 핸들러가 먼저 연결됩니다. 그것은 전파를 차단합니다.`ContactFormHandler`결코 트리거되지 않을 것입니다.</p> </div> <div class="paragraph"> <p>그것은 심지어 활성 버그도 아니다 — 좀비다. 실행될 기회를 갖지 않는 코드.</p> </div> <div id="diag-before" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE title 초기 상태 — 연락처 양식 rectangle "contact.thyme (HTML Bootstrap, honeypot)" as FORM rectangle "footer.thyme (Firebase SDK with config placeholder)" as FOOT rectangle "contact.js\n(모의 Firebase, 85% 성공)" as CONT rectangle "script.js (SupabaseManager + ContactFormHandler, 죽은)" as SCRIPT rectangle "사용자" as USER USER -> FORM : Soumission du formulaire FORM -> CONT : submit event (attaché en premier) CONT -> CONT : preventDefault + stopPropagation CONT -> CONT : mock Promise (1.5s, aléatoire) note right of CONT ⚠️ Aucune donnée stockée end note FORM ..> SCRIPT : submit event (bloqué par stopPropagation) note right of SCRIPT : ❌ Jamais déclenché note right of SCRIPT : ❌ supabase-js non chargé @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_왜_firebase가_supabase_대신인가">왜 Firebase가 Supabase 대신인가?</h2> <div class="sectionbody"> <div class="paragraph"> <p>마이그레이션 결정은 다음에 문서화되어 있습니다.<code>AGENT.adoc</code>:</p> </div> <div class="paragraph"> <p>Firebase는 이제 다음 이유로 선택됩니다: 더 나은 무료 플랜, 네이티브 Firestore, 통합된 Cloud Functions, 더 적합한 Google 생태계. 기존 Supabase 구현은 '⚠️ 폐기됨’으로 표시됩니다.</p> </div> <div class="paragraph"> <p>무료 플랜을 넘어 건축적인 이유가 있습니다. 이 사이트는 Google 생태계 : 대상 저장소는`cheroliv.github.io`, CNAME은 GitHub Pages를 가리키고, Gradle 빌드는 JGit을 통해 GitHub에 푸시됩니다. Firebase와 같은 Google 서비스를 타사 서비스(Supabase) 대신 사용하면 배포 표면이 줄어듭니다.</p> </div> <div class="paragraph"> <p>Firestore를 네이티브 모드(데이터스토어 모드가 아님)로 사용하면 내가 생각하는 NoSQL 문서 모델에 더 가깝습니다: 컬렉션, 문서, 타입이 지정된 필드, 서버 타임스탬프, 내장된 보안 규칙.</p> </div> </div> </div> <div class="sect1"> <h2 id="_1단계_firebase_프로젝트_만들기">1단계: Firebase 프로젝트 만들기</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_초기화">초기화</h3> <div class="paragraph"> <p>내 머신에 Firebase CLI가 설치되어 있지 않아서 웹 콘솔을 사용합니다 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>가다https://console.firebase.google.com/[Firebase Console]</p> </li> <li> <p>프로젝트 생성`cheroliv-contact`( 또는 기존 프로젝트 재사용)</p> </li> <li> <p>네이티브 모드에서 Firestore를 활성화(데이터스토어가 아님)</p> </li> <li> <p>지역에서 데이터베이스 생성`eur3`(유럽)</p> </li> </ol> </div> <div class="paragraph"> <p>우리처럼 단순한 용도(단일 컬렉션, 공개 쓰기)라면 네이티브 모드가 올바른 선택입니다. 복잡한 Datastore 규칙이 필요하지 않습니다.</p> </div> </div> <div class="sect2"> <h3 id="_firestore_보안_규칙">Firestore 보안 규칙</h3> <div class="paragraph"> <p>양식은 공개되어 있습니다 — 누구나 메시지를 보낼 수 있습니다. 하지만 나는 남용을 제한하고 싶습니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">rules_version = '2'; service cloud.firestore { match /databases/{database}/documents { match /contact_messages/{messageId} { // Lecture : admin uniquement (authentifié) allow read: if request.auth != null; // Écriture : publique, mais limitée allow create: if request.auth == null && request.resource.data.name is string && request.resource.data.name.size() >= 1 && request.resource.data.name.size() <= 100 && request.resource.data.email is string && request.resource.data.email.matches('.*@.*\\..*') && request.resource.data.email.size() <= 254 && request.resource.data.subject is string && request.resource.data.subject.size() >= 3 && request.resource.data.subject.size() <= 200 && request.resource.data.message is string && request.resource.data.message.size() >= 10 && request.resource.data.message.size() <= 5000 && request.resource.data.created_at == request.time && request.resource.data.user_agent is string && request.resource.data.user_agent.size() <= 500; } } }</code></pre> </div> </div> <div class="paragraph"> <p>핵심 포인트:</p> </div> <div class="ulist"> <ul> <li> <p><code>allow read</code>— 인증된 사용자만이 메시지를 읽을 수 있습니다 (저, Firebase 콘솔을 통해)</p> </li> <li> <p><code>allow create</code>— 누구나 문서를 만들 수 있지만, 필드 검증과 함께</p> </li> <li> <p>서버 측 검증 : 최소/최대 크기, 이메일 형식,<code>created_at`해야 한다`request.time</code>(위조 방지)</p> </li> <li> <p>`user_agent`추적을 위해 전송됨 (중요하지 않지만 유용함)</p> </li> </ul> </div> <div class="paragraph"> <p>이 규칙들은 더 엄격합니다보다 간단한`allow write: if true;`. 그들이 공격자가 엄청난 페이로드나 잘못된 필드를 주입하는 것을 방지합니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_phase_2_제출_javascript_다시_쓰기">Phase 2 : 제출 JavaScript 다시 쓰기</h2> <div class="sectionbody"> <div class="paragraph"> <p>계약은 간단합니다 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>양식 데이터를 읽다</p> </li> <li> <p>허니팟 확인 (필드`hp_name`— 채워져 있으면 봇이며, 아무것도 보내지 않고 성공을 시뮬레이션합니다)</p> </li> <li> <p>전화하다`addDoc(window.<em>FIREBASE</em>.collection(db, "contact_messages"), {…​})`</p> </li> <li> <p>성공 또는 오류 표시</p> </li> </ol> </div> <div class="sect2"> <h3 id="_의존성_window_firebase">의존성 `window.<em>FIREBASE</em></h3> <div class="paragraph"> <p>안에`footer.thyme`, 스크립트 모듈이 Firebase SDK를 초기화하고 전역 객체를 노출합니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><script type="module"> import { initializeApp } from "https://www.gstatic.com/firebasejs/11.6.0/firebase-app.js"; import { getFirestore, collection, addDoc, serverTimestamp } from "https://www.gstatic.com/firebasejs/11.6.0/firebase-firestore.js"; const firebaseConfig = { /* valeurs réelles */ }; const app = initializeApp(firebaseConfig); const db = getFirestore(app); window.__FIREBASE__ = { db, collection, addDoc, serverTimestamp }; </script></code></pre> </div> </div> <div class="paragraph"> <p>모듈 스크립트는 먼저 실행됩니다`DOMContentLoaded`, 따라서`window.<em>FIREBASE</em>`핸들러가 있을 때 사용 가능하도록 보장됩니다`contact.js`발생합니다. 예방 차원에서, 5초 폴링을 추가로 설정합니다. CDN이 느릴 경우에 대비해.</p> </div> </div> <div class="sect2"> <h3 id="_새로운_contact_js">새로운 `contact.js</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">document.addEventListener('DOMContentLoaded', function () { 'use strict'; const form = document.getElementById('contact-form'); if (!form) return; const submitButton = form.querySelector('button[type="submit"]'); const successMessage = document.getElementById('contact-success-message'); const errorMessage = document.getElementById('contact-error-message'); // Éléments de validation const nameInput = form.querySelector('input[name="name"]'); const emailInput = form.querySelector('input[name="email"]'); const phoneInput = form.querySelector('input[name="phone"]'); const subjectInput = form.querySelector('input[name="subject"]'); const messageInput = form.querySelector('textarea[name="message"]'); const honeypotInput = form.querySelector('input[name="hp_name"]'); /** * Attend que window.__FIREBASE__ soit disponible. * Timeout de 5 secondes — si le CDN Firebase est lent, on abandonne. */ function waitForFirebase(timeoutMs = 5000) { return new Promise((resolve, reject) => { if (window.__FIREBASE__) { resolve(window.__FIREBASE__); return; } const start = Date.now(); const interval = setInterval(() => { if (window.__FIREBASE__) { clearInterval(interval); resolve(window.__FIREBASE__); } else if (Date.now() - start > timeoutMs) { clearInterval(interval); reject(new Error('Firebase SDK non disponible après timeout')); } }, 100); }); } // --- Validation (identique à l'existant) --- function validateForm() { nameInput.setCustomValidity(''); emailInput.setCustomValidity(''); if (phoneInput) phoneInput.setCustomValidity(''); subjectInput.setCustomValidity(''); messageInput.setCustomValidity(''); if (nameInput.value.trim().length < 1) { nameInput.setCustomValidity('Veuillez saisir votre nom.'); } const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/; if (!emailPattern.test(emailInput.value.trim())) { emailInput.setCustomValidity('Veuillez saisir une adresse email valide.'); } if (phoneInput && phoneInput.value.trim() !== '') { const phonePattern = /^\d{10,15}$/; if (!phonePattern.test(phoneInput.value.trim())) { phoneInput.setCustomValidity('Veuillez saisir un numéro valide (10 à 15 chiffres).'); } } if (subjectInput.value.trim().length < 3) { subjectInput.setCustomValidity('Veuillez saisir un sujet (3 caractères minimum).'); } if (messageInput.value.trim().length < 10) { messageInput.setCustomValidity('Veuillez saisir un message (10 caractères minimum).'); } form.classList.add('was-validated'); return form.checkValidity(); } // --- Handler de soumission --- form.addEventListener('submit', async function (event) { event.preventDefault(); event.stopPropagation(); if (!validateForm()) return; // Honeypot : si rempli, simuler un succès sans rien envoyer if (honeypotInput && honeypotInput.value.trim() !== '') { successMessage.style.display = 'block'; form.reset(); form.classList.remove('was-validated'); return; } // UI : état d'envoi submitButton.disabled = true; submitButton.innerHTML = ` <span class="spinner-border spinner-border-sm" role="status" aria-hidden="true"></span> Envoi en cours... `; successMessage.style.display = 'none'; errorMessage.style.display = 'none'; try { const fb = await waitForFirebase(); const messagesCollection = fb.collection(fb.db, 'contact_messages'); await fb.addDoc(messagesCollection, { name: nameInput.value.trim(), email: emailInput.value.trim(), phone: phoneInput ? phoneInput.value.trim() : '', subject: subjectInput.value.trim(), message: messageInput.value.trim(), created_at: fb.serverTimestamp(), user_agent: navigator.userAgent.substring(0, 500) }); successMessage.style.display = 'block'; form.reset(); form.classList.remove('was-validated'); } catch (error) { console.error('Erreur Firestore:', error); errorMessage.style.display = 'block'; } finally { submitButton.disabled = false; submitButton.innerHTML = ` <i class="bi bi-send me-2"></i> Envoyer le Message `; } }, false); });</code></pre> </div> </div> <div class="paragraph"> <p>모의와 비교한 변경 사항 :</p> </div> <div class="ulist"> <ul> <li> <p><code>waitForFirebase()</code>— 타임아웃이 있는 폴링, CDN이 느려도 견고함</p> </li> <li> <p><code>honeypot</code>— 숨은 필드면`hp_name`가 채워졌습니다, 파이어스토어에서 무조건적인 성공을 시뮬레이션합니다. 봉은 성공했다고 생각하지만 아무것도 저장되지 않습니다</p> </li> <li> <p><code>addDoc(collection, {…​})</code>— 실제 Firestore 호출`serverTimestamp()` et <code>user_agent</code></p> </li> <li> <p>오류 처리와 함께`try/catch`비동기</p> </li> <li> <p>청소하는`finally`(버튼 복원)</p> </li> </ul> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>왜`user_agent`? 이것은 선택사항이지만 진단에 유용합니다. 이상한 메시지가 도착했을 때, 그것이 데스크톱 브라우저, 모바일, 또는 curl 스크립트에서 왔는지 아는 것이 분류에 도움이 됩니다.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_3단계_supabase의_죽은_코드_정리">3단계: Supabase의 죽은 코드 정리</h2> <div class="sectionbody"> <div class="paragraph"> <p>`script.js`250줄의 dead code가 포함되어 있습니다:</p> </div> <div class="ulist"> <ul> <li> <p><code>SupabaseManager</code>(라인 417-481) — 65 라인</p> </li> <li> <p><code>ContactFormHandler</code>(490-551번 줄) — 62줄</p> </li> <li> <p>초기화 블록 (줄 645-654) — 10줄</p> </li> </ul> </div> <div class="paragraph"> <p>총 : 약 140줄 삭제</p> </div> <div class="paragraph"> <p>블록`DOMContentLoaded`만든`SupabaseManager`그리고 하나`ContactFormHandler`양식에 연결됨. 앞서 설명한 바와 같이, 이 코드는 결코 실행되지 않습니다(차단된`contact.js`), 심지어 실행되더라도 실패할 것입니다 (Supabase SDK가 로드되지 않음).</p> </div> <div class="paragraph"> <p>삭제합니다 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>클래스`SupabaseManager`</p> </li> <li> <p>수업`ContactFormHandler`</p> </li> <li> <p>초기화 블록 안에`DOMContentLoaded`(줄 645-654)</p> </li> </ol> </div> <div class="paragraph"> <p>Le reste de <code>script.js`정상입니다 :`ThemeManager</code>, <code>ScrollToTopButton</code>, <code>MobileMenuManager</code>, <code>SmoothScrollWithOffset</code>, <code>NavbarHeightUpdater</code>, <code>DynamicNavbarBreakpoint</code>, <code>CodeBlockManager</code>, <code>TooltipManager</code>, <code>PhoneInputManager</code>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_단계_4_푸터_구성">단계 4: 푸터 구성</h2> <div class="sectionbody"> <div class="paragraph"> <p>`footer.thyme`이미 Firebase boilerplate을 가지고 있지만 값이 플레이스홀더인 상태입니다. 나는 교체합니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">const firebaseConfig = { apiKey: "REMPLACER_PAR_VOTRE_API_KEY", authDomain: "REMPLACER_PAR_VOTRE_AUTH_DOMAIN", projectId: "REMPLACER_PAR_VOTRE_PROJECT_ID", storageBucket: "REMPLACER_PAR_VOTRE_STORAGE_BUCKET", messagingSenderId: "REMPLACER_PAR_VOTRE_SENDER_ID", appId: "REMPLACER_PAR_VOTRE_APP_ID" };</code></pre> </div> </div> <div class="paragraph"> <p>실제 값을 가져온 이래<strong>프로젝트 설정 > 일반 > 앱 > 웹 앱</strong>Firebase 콘솔에서.</p> </div> <div class="paragraph"> <p>값은 민감합니다`apiKey`Firebase에서는 설계상 공개되어 있지만, 저는 평문으로 커밋하는 것을 선호하지 않습니다). 저는 그것을 저장합니다`site.yml`(이미 안에`.gitignore`) 및 플러그인`bakery`그들은 빌드 측에 추가해야 할 로직을 통해 템플릿에 주입한다.</p> </div> <div class="paragraph"> <p>당장, 나는 그들을 바로 안에 넣고 있어요.<code>footer.thyme</code>— 빌드`./gradlew serve`로컬에서 로드할 것입니다. 배포 시, 저는 인젝션을 이동시킬 것입니다.`site.yml`또는 Gradle 변수에.</p> </div> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td> <td class="content"> <div class="paragraph"> <p>L'`apiKey`Firebase는 아닙니다.<strong>아니</strong>비밀입니다. 설계상 공개되어 있습니다. 당신의 데이터를 보호하는 것은<strong>Firestore 보안 규칙</strong>, API 키가 아닙니다. 그 안에 넣지 마세요`.env`서버 측에서 로드된 — 브라우저에 노출되도록 의도되었습니다.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_phase_5_최종_아키텍처">Phase 5 : 최종 아키텍처</h2> <div class="sectionbody"> <div id="diag-after" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE title 최종 아키텍처 — 문의 폼 Firebase actor Utilisateur as USER package "브라우저" #E8F5E9 { rectangle "연락.타임\n(HTML, 허니팟)" as FORM rectangle "contact.js\n(유효성 검사 + Firestore)" as CONT rectangle "footer.thyme\n(Firebase SDK 초기화)" as FOOT } cloud "파이어베이스" #BBDEFB { rectangle "Firestore (연락_메시지)" as FS } FORM --> CONT : submit event CONT --> FOOT : window.__FIREBASE__.addDoc() FOOT --> FS : Insert document\n(règles de sécurité validées) note right of FS Firestore Rules : - create: public, validé - read: auth uniquement end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_이_이동이_도그푸딩에_대해_말하는_것">이 이동이 도그푸딩에 대해 말하는 것</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 사이트는 내 자체 Gradle 플러그인으로 생성됩니다.<code>bakery</code>. 연락처 양식은 사이트 내부에 존재합니다. Supabase → Firebase 마이그레이션은 다음에 문서화되어 있습니다.<code>AGENT.adoc</code>, 이 이야기는 백로그에서 논의되며, 이 이야기는 를 통해 테스트됩니다`./gradlew serve`, 그리고 그것은 블로그 포스트(당신이 읽고 있는 글)를 생성합니다.</p> </div> <div class="paragraph"> <p>이것은 순수한 dogfooding이다. 사이트는 플러그인의 제품이고, 플러그인은 개발자의 제품이며, 개발자는 사이트 자체에서 과정을 문서화한다.</p> </div> <div class="paragraph"> <p>루프가 닫혔습니다.</p> </div> <div class="paragraph"> <p>몇 달 동안 모의를 끌고 다녔던 일(양식은 조용히 거짓말을 했던 전체 세션들) 때문에 나는 뭔가를 깨달았다: 개인 정적 사이트의 백로그는 결코 ‘완료’되지 않는다. 항상 우선순위가 있는 US가 있고, 항상 초안인 글이 있고, 항상 템플릿에 주석 처리된 섹션이 있다. 규율은 모든 것을 끝내는 것이 아니라 사용자에게 보이는 것을 끝내는 것이다.</p> </div> <div class="paragraph"> <p>고장난 연락처 양식은 아예 양식이 없는 것보다도 더 나쁘다. 그것은 지키지 못한 약속이다.</p> </div> <div class="sect2"> <h3 id="_수정_사항_요약">수정 사항 요약</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6676%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">파일</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">수정</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">영향</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>blog/2026/0113_*.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">기사 작성</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">문서</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>assets/js/contact.js</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">재작성 (mock → 실제 Firestore)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">기능적인</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>assets/js/script.js</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">삭제 SupabaseManager + ContactFormHandler + 초기화 블록</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">청소</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>templates/footer.thyme</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">구성 요소 플레이스홀더 대체 → 실제 값</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">구성</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_다음_단계_백로그">다음 단계 (백로그)</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><strong>알림 이메일</strong>: 하나의 Cloud Function`onCreate`위에`contact_messages`SendGrid을 통해 메일을 보내는. 폼은 저장되지만 알림을 받지 못합니다. 중위 우선순위 — 메시지가 Firebase 콘솔에서 보입니다.</p> </li> <li> <p><strong>클라이언트 측 요청 제한</strong>: <code>localStorage</code> 타임스탬프를 추가하여 연속적인 다중 제출을 방지합니다. 허니팟은 naïve 봇을 차단하고, 레이트 리미터는 좀 더 교묘한 봇도 차단할 것입니다.</p> </li> <li> <p><strong>테스트</strong>: Playwright 테스트가 폼을 제출하고 Firestore에서 문서가 나타나는지 확인합니다. 현재는 수동으로 테스트하고 있습니다 via`./gradlew serve`.</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_참고문헌">참고문헌</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://firebase.google.com/docs/firestore/security/get-started">Firestore 보안 규칙 문서</a></p> </li> <li> <p><a href="https://firebase.google.com/docs/firestore/manage-data/add-data#add_a_document">Firestore addDoc 문서 — Web v9 모듈형</a></p> </li> <li> <p><a href="/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html">에이전트 거버넌스 시리즈 — 파트 1 : Eager/Lazy</a></p> </li> <li> <p><a href="/blog/2026/0110_mecanisme_backup_contexte_agent_post.html">거버넌스 에이전트 시리즈 — 파트 2 : Hot/Warm/Cold</a></p> </li> <li> <p><a href="/blog/2026/0111_audit_contexte_agent_post.html">에이전트 거버넌스 시리즈 — 파트 3: 감사</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html Tue, 28 Apr 2026 00:00:00 +0000 blog/2026/0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_맥락_시험대가_아닌_공사_현장">맥락 : 시험대가 아닌 공사 현장</a></li> <li><a href="#_내_테스트_환경">내 테스트 환경</a></li> <li><a href="#_평가_그리드">평가 그리드</a></li> <li><a href="#_round_1_kimi_k2_6_거짓_출발">Round 1 : Kimi K2.6 — 거짓 출발</a> <ul class="sectlevel2"> <li><a href="#_세션_9_호전">세션 9: 호전</a></li> <li><a href="#_세션_10_침묵의_난파">세션 10 : 침묵의 난파</a></li> </ul> </li> <li><a href="#_라운드_2_glm_5_1_명예로운_전투원">라운드 2 : GLM-5.1 — 명예로운 전투원</a> <ul class="sectlevel2"> <li><a href="#_아키텍처_dsa_대_순수_mla">아키텍처 : DSA 대 순수 MLA</a></li> <li><a href="#_세션_11_13_단단하지만_짜증나는">세션 11-13: 단단하지만 짜증나는</a></li> </ul> </li> <li><a href="#_라운드_3_deepseek_v4_pro_전쟁_기계">라운드 3 : DeepSeek-V4-Pro — 전쟁 기계</a> <ul class="sectlevel2"> <li><a href="#_아키텍처_csa_hca_이중_필렛">아키텍처 : CSA + HCA, 이중 필렛</a></li> <li><a href="#_세션_1_8_완화">세션 1-8 : 완화</a></li> <li><a href="#_결정적인_테스트_100k_토큰_규모의_리팩터링">결정적인 테스트: 100K 토큰 규모의 리팩터링</a></li> </ul> </li> <li><a href="#_대면_비교_지표">대면: 비교 지표</a></li> <li><a href="#_왜_deepseek_v4_pro가_소프트웨어_개발에서_승리하는가">왜 DeepSeek-V4-Pro가 소프트웨어 개발에서 승리하는가</a> <ul class="sectlevel2"> <li><a href="#_1_csahca_아키텍처는_코드에_맞게_설계되었습니다">1. CSA+HCA 아키텍처는 코드에 맞게 설계되었습니다.</a></li> <li><a href="#_2_eager_컨텍스트는_그의_편안한_영역이다">2. EAGER 컨텍스트는 그의 편안한 영역이다</a></li> <li><a href="#_3_품질지연_비율이_흐름에_최적입니다">3. 품질/지연 비율이 흐름에 최적입니다.</a></li> </ul> </li> <li><a href="#_배운_교훈_vibe_coding을_위한_llm_선택_방법">배운 교훈 : Vibe Coding을 위한 LLM 선택 방법</a></li> <li><a href="#_그리고_거버넌스_에이전트는_이_모든_상황에서_어떤가요">그리고 거버넌스 에이전트는 이 모든 상황에서 어떤가요?</a></li> <li><a href="#_기술적_출처">기술적 출처</a></li> <li><a href="#_결론_장인의_선택">결론 : 장인의 선택</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽기 시간 : 18 minutes</div> <p>LLM 전쟁도 개발자 터미널에서 이루어진다. 무의미한 학술적 벤치마크가 아니라. 실제 생활에서는: 30,000 토큰 프롬프트, AsciiDoc 기반 에이전트 거버넌스, 디버그해야 하는 Gradle Kotlin DSL 플러그인, 그리고 3주 동안 이어지는 세션. 저는 여러분을 위해 DeepSeek-V4-Pro, Kimi K2.6, GLM-5.1을 테스트해 보았습니다. 여기서 기술적 증거를 바탕으로 한 평결을 제시합니다.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">틱</dt> <dd> <p></think></p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_맥락_시험대가_아닌_공사_현장">맥락 : 시험대가 아닌 공사 현장</h2> <div class="sectionbody"> <div class="paragraph"> <p>3주 전, 나는 …​에 대해 일하고 있었다`codebase-gradle`, 내 메타빌드 시스템은 YAML 구성 중앙화하여 네 개의 프로젝트 — PlantUML README 생성기, AsciiDoc 슬라이드 빌더, 정적 JBake 사이트, LLM 챗봇 — 을 관리합니다. Opencode 에이전트는 AsciiDoc 형식의 내 에이전트 파일 방법론에 따라 매 세션 시작 시 약 30K 토큰의 EAGER 컨텍스트를 로드했습니다 — 절대 규칙, 백로그, 마지막 10개 세션 기록.</p> </div> <div class="paragraph"> <p>이 현장에서 나는 세 가지 모델을 맞섰다:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Kimi K2.6</strong>(Moonshot AI, 1T 파라미터 / 32B 활성화, 256K 최대 컨텍스트, MLA) - <strong>GLM-5.1</strong>(Zhipu AI/Tsinghua, 744B params / DSA, 200K 컨텍스트 max) - <strong>DeepSeek-V4-Pro</strong>(DeepSeek, 1.6T 파라미터 / 49B 활성화, 1M 최대 컨텍스트, CSA+HCA)</p> </li> </ul> </div> <div class="paragraph"> <p>모든 것이 클라우드 서버의 Ollama를 통해 제공되며, 모두 thinking 모드(반사 단계 활성화)로 실행됩니다. 과제 : 올바른 코드를 생산하고, 긴 세션 동안 일관성을 유지하며, 컨텍스트가 80K 토큰을 초과할 때 환각을 일으키지 않는 것입니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_내_테스트_환경">내 테스트 환경</h2> <div class="sectionbody"> <div id="diag-dev-env" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 220 title 테스트 환경 — Opencode 세션 × 3 LLMs left to right direction package "🖥️ 개발자 터미널" #E8F5E9 { rectangle "AGENT.adoc (규칙, 백로그)" as AG rectangle "PROMPT_REPRISE (임무)" as PR rectangle "INDEX.adoc (로드맵)" as IDX } package "☁️ 올라마 클라우드" #BBDEFB { rectangle "DeepSeek-V4-Pro\n1.6T / CSA+HCA" as DV4 rectangle "Kimi K2.6 1T / MLA" as KIMI rectangle "GLM-5.1 744B / MLA+DSA" as GLMG } package "⚙️ Gradle 코드베이스" #FFF9C4 { folder "buildSrc/" { file "codebase.kt" file "readme.kt" file "site.kt" file "slider.kt" file "snapshot.kt" } file "build.gradle.kts (947줄)" file "embeds.yml" } AG --> DV4 : Sessions 1-8 ✅ AG --> KIMI : Sessions 9-10 ⚠️ AG --> GLMG : Sessions 11-13 ⚠️ DV4 --> "코드베이스" : "TDD, 리팩터링,\n스냅샷" KIMI --> "코드베이스" : "성능 저하 60K 토큰부터" note bottom of GLMG Meilleur que Kimi mais latence + DSA moins robuste que CSA+HCA end note @enduml</pre> </div> </div> <div class="paragraph"> <p>각 세션은 약 30K 토큰의 EAGER 컨텍스트로 시작했습니다 :`AGENT.adoc`(287줄)<code>PROMPT_REPRISE.adoc</code>(51줄),<code>.agents/INDEX.adoc</code>(218줄),<code>LAZY_EAGER_ESSENTIALS.adoc</code>(50줄). 컨텍스트가 교환과 함께 빠르게 커졌습니다 — 일반적인 10 메시지 세션은 누적 프롬프트에 15-20K 토큰을 추가했습니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_평가_그리드">평가 그리드</h2> <div class="sectionbody"> <div class="paragraph"> <p>저는 각 모델을 보조 소프트웨어 개발을 위한 네 가지 중요한 평가 기준으로:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">도끼</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">구체적인 기준</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>장거리 맥락 일관성</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">에이전트는 40개 메시지 전에 정해진 협약을 기억하고 있나요?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>생산된 코드의 품질</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">코드가 처음에 바로 컴파일됩니까? 기존 패턴을 준수합니까?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>건축적 추론</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">에이전트가 내가 다시 설명하지 않아도 모듈 간의 관계를 이해하고 있나요?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>환각 저항</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">몇 토큰부터 에이전트가 존재하지 않는 API 또는 클래스를 만들어내기 시작하나요?</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>그리고 자체 제작 합성 지표 : 그<strong>회복 계수</strong>(내가 에이전트를 고치는 데 드는 시간이 그와 함께 코딩하는 데 드는 시간보다 얼마나 긴가).</p> </div> </div> </div> <div class="sect1"> <h2 id="_round_1_kimi_k2_6_거짓_출발">Round 1 : Kimi K2.6 — 거짓 출발</h2> <div class="sectionbody"> <div class="paragraph"> <p>Kimi K2.6는 나의 첫 번째 선택이었다. 그의 SWE-Bench Verified (80.2)와 Terminal-Bench 2.0 (66.7) 벤치마크는 훌륭하다. 그의 MLA 아키텍처는 긴 시퀀스에 대한 좋은 효율성을 약속한다.</p> </div> <div class="sect2"> <h3 id="_세션_9_호전">세션 9: 호전</h3> <div class="paragraph"> <p>Kimi와의 첫 번째 세션. 작업: 메서드 구현`resolveActiveKey()<code>안에`codebase.kt</code>— API 키를 해결하는 함수이며 CLI 폴백을 갖는 함수. 컨텍스트는 30K 토큰이며, Kimi는 빠르게 추론하고 키 만료 관리가 있는 깨끗한 코드를 생성합니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">fun resolveActiveKey( cfg: CodebaseConfiguration, logger: Logger, cliProvider: String? = null, cliAccount: String? = null, cliKey: String? = null ): NamedApiKey? { // Résolution provider → compte → clé avec CLI override // Kimi a parfaitement compris la chaîne de priorité }</code></pre> </div> </div> <div class="paragraph"> <p>코드가 컴파일됩니다. 7개의 테스트 케이스가 통과됩니다. 저는 낙관적입니다.</p> </div> </div> <div class="sect2"> <h3 id="_세션_10_침묵의_난파">세션 10 : 침묵의 난파</h3> <div class="paragraph"> <p>두 번째 세션. 컨텍스트가 교환으로 인해 약 90K 토큰까지 증가합니다. 나는 Kimi에게 AsciiDoc 스냅샷 메커니즘을 추가하여 글을 쓰기 전에 비밀을 익명화하도록 요청한다.</p> </div> <div class="paragraph"> <p>여기서부터 일이 꼬이기 시작해. 기미는 존재하지 않는 클래스를 발명하기 시작한다. 그는 나에게 제안한다.<code>AnonymizedObjectMapper</code>— 가상의 클래스. 그는 혼동한다`ReadmeYmlAnonymizer` et <code>CodebaseYmlAnonymizer</code>. 그가 내게 수입하라고 제안한다`com.fasterxml.jackson.anonymize.*`— 존재한 적이 없는 패키지.</p> </div> <div class="paragraph"> <p>더욱이: 그의 반성 단계에서, 나는 그가 잘못된 전제에 기반하여 논리를 구성하고 있다는 것을 본다. 그는 "기억한다"고 한다`GitConfig`필드가 있습니다`anonymizedToken`— 아니, 그것이`resolvedToken()<code>.그는 …​에 돌린다`SiteYmlAnonymizer`방법`maskSupabaseCredentials()</code>— 존재하지 않는.</p> </div> <div class="paragraph"> <p><em><em>_ 이게 버그가 아니었다. 그것은 일관성의 점진적인 소멸이었다. 마치 컨텍스트에 추가된 각 토큰이 처음 30,000개의 메모리를 점점 더 희석시키는 것처럼. </em>_</em></p> </div> <div class="paragraph"> <p>두 세션 후에 Kimi를 멈춥니다. 진단은 명확합니다: MLA는 KV 캐시를 잘 압축하지만, 미세한 희소 선택 메커니즘이 없으면 주의가 60K 토큰을 넘어가면서 기계적으로 희석됩니다. 각 토큰은 먼 컨텍스트를 점점 더 잘 볼 수 없게 되고 — 빈틈을 소음으로 채우기 시작합니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_라운드_2_glm_5_1_명예로운_전투원">라운드 2 : GLM-5.1 — 명예로운 전투원</h2> <div class="sectionbody"> <div class="paragraph"> <p>GLM-5.1은 다른 아키텍처와 함께 제공됩니다: 기본 모델에 대한 MLA, 이어서 DSA(DeepSeek Sparse Attention)를 사용한 <strong>continued pre-training</strong> — 전체 기록에서 관련 있는 상위 2048 토큰을 동적으로 선택하는 가벼운 인덱서.</p> </div> <div class="sect2"> <h3 id="_아키텍처_dsa_대_순수_mla">아키텍처 : DSA 대 순수 MLA</h3> <div class="paragraph"> <p>차이는 근본적이다. Kimi가 기록을 단일 잠재 공간에 압축할 때(그리고 점차적으로 관련 정보를 구분하는 능력을 잃을 때), GLM은 사후 훈련된 인덱서를 삽입하여 명시적인 희소 선택을 수행한다.</p> </div> <div id="diag-mla-vs-dsa" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title 어텐션 아키텍처 — MLA vs MLA+DSA left to right direction rectangle "Kimi K2.6 — MLA 순수한" as MLA #FFCDD2 { rectangle "KV 캐시 완전" as KV1 rectangle "잠재 압축" as CL1 rectangle "디코딩 잠재 공간에서" as DL1 KV1 --> CL1 CL1 --> DL1 note bottom of DL1 ⚠️ Au-delà de 60K tokens : perte de discrimination end note } rectangle "**GLM-5.1 — MLA + DSA**" as DSA #C8E6C9 { rectangle "KV 캐시 완전" as KV2 rectangle "잠재적 압축 (MLA)" as CL2 rectangle "경량 인덱서\n(DSA, top-k=2048)" as IL rectangle "디코딩 선택된 토큰에 대한" as DL2 KV2 --> CL2 CL2 --> IL IL --> DL2 note bottom of DL2 ✅ "구조상 무손실" Sélection explicite des tokens pertinents end note } MLA --> DSA : "이득 : 희소 선택 희석을 피하는" @enduml</pre> </div> </div> <div class="paragraph"> <p>기술 보고서는 명시적으로 다음과 같이 말합니다: DSA는 <em>"lossless by construction"</em> — SWA (패턴 검색), Gated DeltaNet 또는 SimpleGDN과 같은 대안들과 달리, 이들은 RULER@128K에서 최대 5.69포인트를 잃습니다.</p> </div> </div> <div class="sect2"> <h3 id="_세션_11_13_단단하지만_짜증나는">세션 11-13: 단단하지만 짜증나는</h3> <div class="paragraph"> <p>GLM-5.1이 거리를 더 잘 유지합니다. 세션 11 (~60K 토큰)에서 일관성을 유지합니다. 그것은 생산하는`SnapshotManager`네 개의 익명화 도구를 올바르게 관리하는 기능적인</p> </div> <div class="paragraph"> <p>하지만 지연은 문제입니다. DSA 반사 단계는 순수 MLA보다 더 무겁습니다 — 인덱서는 각 단계에서 기록을 다시 스캔해야 합니다. Kimi로는 8초가 걸리던 응답이 GLM에서는 15초가 걸립니다. 30개의 메시지로 구성된 세션에서는 이것이 느껴집니다.</p> </div> <div class="paragraph"> <p>그리고 미묘한 오류들이 있습니다. GLM은 Kimi처럼 환각을 일으키지 않지만, <strong>이름 지정</strong> 오류를 합니다. 그것은 호출한다`toAnonymizedYaml()<code>호출되어야 하는 메서드`anonymize()`python print(". 뒤집합니다", end='')`loadReadmeConfiguration()</code> et <code>loadCodebaseConfiguration()`안에`renderFileSection()</code>. 이건 환각이 아니라 표면적인 혼란이지만 — 하지만 프로덕션에서 표면적인 혼란은 빌드를 깨뜨릴 수 있다.</p> </div> <div class="paragraph"> <p>GLM과 세 번의 세션을 가졌다. 그는 Kimi보다 확실히 더 낫다. 하지만 이름 지정 세부 사항에 대한 수작업 세 세션은 지치게 만든다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_라운드_3_deepseek_v4_pro_전쟁_기계">라운드 3 : DeepSeek-V4-Pro — 전쟁 기계</h2> <div class="sectionbody"> <div class="paragraph"> <p>DeepSeek-V4-Pro는 세 가지 중 가장 야심찬 아키텍처를 탑재하고 출시됩니다: 서로 보완적인 두 주의 메커니즘을 결합하는 하이브리드 시스템입니다.</p> </div> <div class="sect2"> <h3 id="_아키텍처_csa_hca_이중_필렛">아키텍처 : CSA + HCA, 이중 필렛</h3> <div id="diag-csa-hca" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 180 title DeepSeek-V4-Pro — 하이브리드 아키텍처 CSA + HCA left to right direction rectangle "KV 캐시 1M 토큰" as KV #E3F2FD rectangle "CSA 압축 희소 어텐션" as CSA #C8E6C9 { rectangle "압축 m 토큰 → 1" as CC rectangle "희소 어텐션 (DSA, 상위 k)" as SA CC --> SA note bottom of SA Attention locale fine + sélection sparse end note } rectangle "HCA 매우 압축된 주의" as HCA #BBDEFB { rectangle "극한 압축\nm' >> m → 1" as ECC rectangle "밀집된 주의 잔여" as EDA ECC --> EDA note bottom of EDA Contexte global + connexions longue distance end note } rectangle "융합 하이브리드" as FUSION #FFF9C4 rectangle "디코딩 일관된" as DEC #FFE0B2 KV --> CSA : Précision locale KV --> HCA : Vision globale CSA --> FUSION HCA --> FUSION FUSION --> DEC @enduml</pre> </div> </div> <div class="paragraph"> <p>압축의 두 단계, 주의의 두 가지 세밀도:</p> </div> <div class="ulist"> <ul> <li> <p><strong>CSA</strong>: KV 캐시를 모두 압축합니다`m`토큰, 그다음 DeepSeek Sparse Attention(희소 주의) 방식을 적용합니다 — 압축된 입력의 상위 k개만이 조회됩니다. 정확하고, 지역적이며, 효율적입니다. - <strong>HCA</strong>: 극도의 압축 (요인`m'`훨씬 더 큰`m`), 하지만 압축된 잔여물에 대한 촘촘한 주의 — 제곱 폭발 없이 전역 연결 유지</p> </li> </ul> </div> <div class="paragraph"> <p>결과 : 1M 토큰에서 DeepSeek-V4-Pro는 단지 소비한다<strong>27%의 추론 FLOPs</strong> et <strong>10%의 KV 캐시 크기</strong>DeepSeek-V3.2와 비교하여. 이전 모델.</p> </div> <div class="paragraph"> <p>그리고 무엇보다, 기술 보고서(그림 9)는 다음과 같이 발표합니다: <em>"Retrieval performance remains highly stable within a 128K context window."</em></p> </div> </div> <div class="sect2"> <h3 id="_세션_1_8_완화">세션 1-8 : 완화</h3> <div class="paragraph"> <p>나는 DeepSeek-V4-Pro와 함께 여덟 번의 세션을 보냈고 그것에 대해`codebase-gradle`. 환각 없이, 발명된 클래스 없이, 이름 지정 혼동 없이 여덟 회의 세션이었습니다.</p> </div> <div class="paragraph"> <p>세션 1: 구현`CodebaseYmlConfig` et <code>CodebaseYmlAnonymizer</code>. 350줄의 Kotlin, 인라인 테스트, 모두 컴파일됨. 세션 4: 추가`SnapshotManager`트리 뷰, 파일 수집, 파일당 AsciiDoc 렌더링. 279줄, 오류 없음. 세션 7: 디버그 du`renderFileSection()`네 가지 유형의 다른 익명화 도구를 해결 모호함 없이 관리해야 했고, 세 개의 메시지로 해결되었습니다.</p> </div> <div class="paragraph"> <p>지연이 Kimi보다 더 높습니다 — 생각 모드에서 응답당 약 10-12초 정도입니다. 하지만 수정률은 거의 제로입니다. 저는 에이전트의 오류를 고치는 데 시간을 보내지 않습니다. 저는 코딩합니다 <strong>avec</strong> 그.</p> </div> </div> <div class="sect2"> <h3 id="_결정적인_테스트_100k_토큰_규모의_리팩터링">결정적인 테스트: 100K 토큰 규모의 리팩터링</h3> <div class="paragraph"> <p>8회차 세션에서 누적된 컨텍스트가 100K 토큰을 초과합니다. 저는 무거운 리팩터링을 요청합니다: 인라인 검증 작업 네 가지를 추출하는`build.gradle.kts`JUnit5 테스트 파일 쪽으로 안에`buildSrc/src/test/`.</p> </div> <div class="paragraph"> <p>대리인은 3단계 계획을 제안합니다:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>기존 사례를 마이그레이션하여 테스트 클래스 생성</p> </li> <li> <p>JUnit5와 Kotest 의존성을 추가`buildSrc/build.gradle.kts`</p> </li> <li> <p>인라인 코드를 삭제하다 의`build.gradle.kts`</p> </li> </ol> </div> <div class="paragraph"> <p>계획이 정확합니다. 실행이 깔끔합니다. 그조차도 내가 놓친 엣지 케이스를 식별합니다: 중복된 Jackson 의존성 사이`buildscript {}` et `buildSrc/build.gradle.kts`마이그레이션 중에 통합되어야 하는</p> </div> <div class="paragraph"> <p>100K 컨텍스트 토큰, 그리고 에이전트는 기억합니다`CodebaseYmlAnonymizer.TOKEN_MASK`이다`"<strong>*</strong>"`, 라고`GitConfig.resolvedToken()<code>는에서`readme.kt</code>, 그리고`SnapshotManager.PRUNED_DIRS`제외한다`build`, <code>.gradle</code> et <code>.git</code>.</p> </div> <div class="paragraph"> <p>그게 차이야.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_대면_비교_지표">대면: 비교 지표</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">기준</th> <th class="tableblock halign-left valign-top">Kimi K2.6</th> <th class="tableblock halign-left valign-top">GLM-5.1</th> <th class="tableblock halign-left valign-top">DeepSeek-V4-Pro</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">최대 문맥</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">256K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">200K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1M</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">주의 메커니즘</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">MLA 순수한</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">MLA + DSA</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">CSA + HCA 하이브리드</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">총 파라미터</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1T</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">744B</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1.6테라</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">활성화된 설정</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">32B</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">게시되지 않은</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">49B</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">관측된 열화 임계치</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~60K tokens</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~120K tokens</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~128K tokens</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">행동을 넘어</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">대규모 환각</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">표면상의 혼동</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">천천히 진행되는 열화</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">안정성 NIAH</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">미공개된</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">100% @128K (DSA)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">128K까지 안정적 (도표 9)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">MRCR @128K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">미발표</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">미발표된</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Gemini 3.1 Pro보다 우수함</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">포기 전에 진행된 세션</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8 (계속)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">수정 시간 / 코딩 시간</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">60%</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">30%</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><5%</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">평균 지연 시간 (think 모드)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8 s</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">15 s</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">11 s</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">신뢰도 계수*</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2/10</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">6/10</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">9/10</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><em>*신뢰 계수 = 에이전트의 코드와 커밋을 줄 단위로 검토하지 않고 가져올 수 있는 나의 능력에 대한 주관적 측정.</em></p> </div> <div id="diag-radar" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title 레이더 비교 — 3개의 LLM 지원된 소프트웨어 개발 legend right |= Couleur |= Modèle | | <#FF5252> | Kimi K2.6 | | <#FFC107> | GLM-5.1 | | <#4CAF50> | DeepSeek-V4-Pro | endlegend rectangle " " as space #FFFFFF rectangle "일관성 80K+ 토큰" as coh #F5F5F5 rectangle "품질\n코드" as qual #F5F5F5 rectangle "건축적 사고" as arch #F5F5F5 rectangle "저항 환각" as hall #F5F5F5 rectangle "속도\n(개발 경험)" as speed #F5F5F5 rectangle "지식 Gradle/Kotlin" as kg #F5F5F5 rectangle "수정\n비율" as corr #F5F5F5 coh --> qual qual --> arch arch --> hall hall --> speed speed --> kg kg --> corr note top of coh Kimi ████░░░░░░ 4/10 GLM ██████░░░░ 6/10 DeepSeek █████████░ 9/10 end note note top of qual Kimi ███████░░░ 7/10 (sous 60K) GLM ████████░░ 8/10 DeepSeek █████████░ 9/10 end note note top of arch Kimi █████░░░░░ 5/10 GLM ███████░░░ 7/10 DeepSeek █████████░ 9/10 end note note top of hall Kimi ██████░░░░ 6/10 → ██░░░░░░░░ 2/10 (> 60K) GLM ███████░░░ 7/10 DeepSeek █████████░ 9/10 end note note top of speed Kimi █████████░ 9/10 GLM ██████░░░░ 6/10 DeepSeek █████░░░░░ 5/10 end note note top of kg Kimi ███████░░░ 7/10 GLM ███████░░░ 7/10 DeepSeek █████████░ 9/10 end note note top of corr Kimi ██░░░░░░░░ 2/10 (beaucoup de corrections) GLM █████░░░░░ 5/10 DeepSeek ██████████ 10/10 (presque rien à corriger) end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_왜_deepseek_v4_pro가_소프트웨어_개발에서_승리하는가">왜 DeepSeek-V4-Pro가 소프트웨어 개발에서 승리하는가</h2> <div class="sectionbody"> <div class="paragraph"> <p>DeepSeek-V4-Pro의 우수성은 단일 요인 때문이 아닙니다 — 그것은 수렴입니다:</p> </div> <div class="sect2"> <h3 id="_1_csahca_아키텍처는_코드에_맞게_설계되었습니다">1. CSA+HCA 아키텍처는 코드에 맞게 설계되었습니다.</h3> <div class="paragraph"> <p>지원되는 소프트웨어 개발은 장기 컨텍스트 주의를 위한 <strong>극한</strong> 사용 사례입니다. 다음과 같이 필요합니다: - 현지 정확도 (이 클래스는 무엇을 상속받았나요? 이 메서드는 어디서 정의되었나요?) →<strong>CSA</strong> - 전체적인 비전 (이 모듈이 왜 존재하는가? 네 개의 익명화 도구가 어떻게 상호작용하는가?) →<strong>HCA</strong></p> </div> <div class="paragraph"> <p>Kimi는 MLA만으로 로컬 정확성을 관리하지만 60K 이상에서는 글로벌 시각을 잃습니다. GLM은 DSA로 글로벌 시각을 개선하지만 단일 수준에 머무릅니다. DeepSeek은 두 가지를 명시적으로 결합합니다.</p> </div> </div> <div class="sect2"> <h3 id="_2_eager_컨텍스트는_그의_편안한_영역이다">2. EAGER 컨텍스트는 그의 편안한 영역이다</h3> <div class="paragraph"> <p>내 거버넌스 시스템은 시작 시 약 30K 토큰의 규칙과 백로그를 로드합니다. 128K까지 안정적인 창을 가지면, DeepSeek은 세션 교환을 위한 약 100K 토큰의 여유를 갖습니다. 이는 Kimi가 성능 저하 없이 처리할 수 있는 양의 3~4배입니다.</p> </div> <div class="paragraph"> <p><em><em>_ 완벽한 안정성을 위한 128K 창은 정확히 내 필요에 맞습니다: EAGER 30K + 교환 70K = 녹색 구역을 벗어나지 않는 20-30 메시지의 생산적인 세션. </em>_</em></p> </div> </div> <div class="sect2"> <h3 id="_3_품질지연_비율이_흐름에_최적입니다">3. 품질/지연 비율이 흐름에 최적입니다.</h3> <div class="paragraph"> <p>예, DeepSeek-V4-Pro는 Kimi보다 느립니다 (11초 vs 8초). 하지만 작업의 <strong>total</strong> 시간이 훨씬 짧습니다. 왜냐하면 에이전트의 환각을 수정하는 데 20분을 쓰지 않기 때문입니다.</p> </div> <div class="paragraph"> <p>개발자는 응답의 지연 시간을 측정하지 않습니다. '질문을 던지는 순간’과 '코드가 내 저장소에 들어 있고 작동하는' 사이의 시간을 측정합니다. 이 지표에서 DeepSeek-V4-Pro가 세 가지 중 가장 빠릅니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_배운_교훈_vibe_coding을_위한_llm_선택_방법">배운 교훈 : Vibe Coding을 위한 LLM 선택 방법</h2> <div class="sectionbody"> <div class="paragraph"> <p>순위를 넘어 이 경험은 보조 소프트웨어 개발을 위한 LLM을 평가하는 방법을 가르쳐 주었는데, 이는 어떤 벤치마크에도 포함되지 않은 기준으로 평가하는 것입니다 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>아키텍처를 봐, 발표된 컨텍스트 크기는 보지 마.</strong>— 모델이 256K 컨텍스트를 발표하지만 MLA 하나만 있다면 Kimi처럼 끝날 것이다: 이론적으로는 가능하지만 실제로 60K를 넘어서는 사용 불가.</p> </li> <li> <p><strong>당신의 컨텍스트에서 테스트하고, 일반적인 벤치마크에서는 테스트하지 마세요</strong>내 초기 30K 토큰 AsciiDoc 프롬프트, 절대 규칙과 백로그를 갖춘 것은 HLE 또는 AIME 질문과 아무 관련이 없다.</p> </li> <li> <p><strong>지연이 적이 아니며, 품질이 따라올 때</strong>— 느린 모델이 올바른 코드를 생성하는 것은 빠른 모델이 잘못된 코드를 생성하는 것보다 빠르다.</p> </li> <li> <p><strong>공개된 기술 보고서가 없는 모델에 주의해</strong>— 팀이 어텐션 아키텍처를 문서화하지 않는다면, 그것은 장기 컨텍스트에서의 성능에 대한 신뢰가 부족하기 때문이다.</p> </li> </ol> </div> <div id="diag-decision-tree" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 260 title 결정 트리 — Dev Assisté를 위한 LLM 선택하기 start :Contexte initial\n> 20K tokens ?; if (Oui) then :Architecture d'attention\nhybride ou multi-niveau ?; if (CSA+HCA) then :DeepSeek-V4-Pro Fenetre stable 128K Ideal pour gouvernance EAGER; stop elseif (MLA + DSA) then :GLM-5.1 Correct jusqu'a ~120K Latence elevee; stop else (MLA seul) :Kimi K2.6 (sessions courtes) ou eviter pour long contexte Chercher un modele avec sparse attention; stop endif else (Contexte < 20K) :N'importe lequel fonctionne. Privilegier la latence.; stop endif @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_그리고_거버넌스_에이전트는_이_모든_상황에서_어떤가요">그리고 거버넌스 에이전트는 이 모든 상황에서 어떤가요?</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 경험은 내가 Eager/Lazy 거버넌스에 관한 나의 기사에서 주장해 온 점을 검증한다:<strong>LLM의 품질과 거버넌스의 품질은 곱셈적이며, 가법적이지 않다</strong>.</p> </div> <div class="paragraph"> <p>Kimi K2.6를 사용했을 때, 나의 거버넌스는 완벽했지만 — 모델이 정보를 희석시켰다. 결과: 완벽한 거버넌스 × 환각 = 0.</p> </div> <div class="paragraph"> <p>DeepSeek-V4-Pro와 함께, EAGER 거버넌스 (규칙 토큰 30K) + LAZY (세션 아카이브, 기술 참조) + Hot/Warm/Cold (회전 백업)은 각 층이 서로를 증폭시키는 생태계를 형성합니다. 에이전트는 규칙을 바로 볼 수 있습니다 (EAGER), 기록을 확인할 수 있습니다 (LAZY), 그리고 컨텍스트가 포화되지 않습니다 (회전 백업).</p> </div> <div class="paragraph"> <p><em><em>_ 거버넌스가 없는 좋은 LLM은 핸들이 없는 Ferrari 엔진이다. 좋은 LLM이 없는 좋은 거버넌스는 엔진이 없는 핸들이다. DeepSeek-V4-Pro + 나의 거버넌스 에이전트 = 운전을 한다는 느낌을 처음으로 갖게 된 순간. </em>_</em></p> </div> <div class="paragraph"> <p>회전식 백업 메커니즘(10 세션마다 또는 EAGER 라인 >500줄일 때 회전)은 128K 컨텍스트를 유지하는 모델과 함께 의미가 생깁니다: 활성 세션 10개의 슬라이딩 윈도우는 컨텍스트를 최신 상태로 유지하면서 절대 degradation 영역을 초과하지 않습니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_기술적_출처">기술적 출처</h2> <div class="sectionbody"> <div class="paragraph"> <p>저는 내 실증적 경험을 공식 기술 보고서와 비교하여 내 관찰을 검증했습니다 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>DeepSeek-V4 Technical Report</strong> — 에서 다운로드된 PDFhttps://huggingface.co/deepseek-ai/DeepSeek-V4-Flash[허깅페이스]. 그림 9 : "검색 성능은 128K 컨텍스트 창 내에서 매우 안정적으로 유지됩니다. 128K 지점을 넘어가면 성능 저하가 보이기 시작하지만, 1M 토큰에서의 모델의 검색 기능은 놀랍도록 강력하게 유지됩니다." CSA+HCA 아키텍처 문서화 섹션 2.3</p> </li> <li> <p><strong>GLM-5 기술 보고서</strong> —https://arxiv.org/abs/2602.15763[arXiv:2602.15763]. DSA는 continued pre-training을 통해 도입되었으며, "lossless by construction". 최대 컨텍스트 202,752 토큰. 표 3/5/6은 장기 컨텍스트 성능을 대안(SWA, Gated DeltaNet, SimpleGDN)과 비교하여 문서화합니다.</p> </li> <li> <p><strong>Kimi K2.6 모델 카드</strong> —https://huggingface.co/moonshotai/Kimi-K2.6[허깅페이스]. MLA, 256K 최대 컨텍스트. 에이전트 작업에서 임계값을 초과한 discard-all 전략(장기 컨텍스트에서 MLA의 실질적 한계를 암시적으로 확인).</p> </li> <li> <p><strong>키미 K2 기술 보고서</strong> —https://arxiv.org/abs/2507.20534[arXiv:2507.20534]. 아키텍처 MoE, MuonClip 옵티마이저, 에이전트 성능 (HLE, BrowseComp, Terminal-Bench).</p> </li> </ol> </div> <div class="paragraph"> <p>가장 드러나는 점: 자체 평가에서 Moonshot은 컨텍스트 창이 초과되자마자 <strong>discard-all</strong>(오래된 컨텍스트 삭제) 전략을 적용합니다. 이는 제가 관찰한 바를 정확히 확인해 줍니다: MLA만으로는 256K 창 전체에서 일관성을 유지할 수 없습니다. 아키텍처가 따라가지 못합니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_결론_장인의_선택">결론 : 장인의 선택</h2> <div class="sectionbody"> <div class="paragraph"> <p>3주와 13번의 실제 개발 세션 후, 판결은 확정적이다:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3337%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Kimi K2.6</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">GLM-5.1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek-V4-Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">60K 미만의 훌륭한</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">최대 120K까지 견고함</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">어디서나 지배한다</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">그 이상은 사용할 수 없습니다</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">표면 혼란</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">128K까지 안정적</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">포기된 2 세션</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3회 세션, 포기된</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8세션, 채택된</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>DeepSeek-V4-Pro`는 `Opencode`을 사용한 모든 소프트웨어 개발 지원 세션의 기본 LLM이 되었습니다. 최신이라서가 아닙니다. 학술적 벤치마크가 최고라서도 아닙니다. 하지만 개발자가 30K 토큰 에이전트 컨텍스트와 함께 Gradle Kotlin DSL 플러그인을 푸시하는 실제 상황에서는, 컨텍스트가 길어질 때도 나를 배신하지 않는 유일한 모델입니다.</p> </div> <div class="paragraph"> <p>CSA+HCA는 아키텍처적 게임 체인저입니다. 이중 레벨 압축 + 스파시피케이션은 구현 세부 사항이 아니라 — 코드 어시스턴트와 신뢰할 수 있는 팀원 사이의 차이를 만드는 요소입니다.</p> </div> <div class="paragraph"> <p><em>__</em> 나는 DeepSeek-V4-Pro를 선택했는데, 이는 세 개 중 오직 하나만이 내 에이전트 거버넌스를 방어적 제약("에이전트가 잊지 않도록 어떻게 방지할까?")에서 공격적 장점("에이전트가 모든 것을 기억한다면 지금 무엇을 건설할 수 있을까?")으로 바꾸기 때문이다. (empty)</p> </div> <hr> <div class="paragraph"> <p><strong>이 글은 프로젝트에서 진행된 실제 개발 13세션의 결과이다.<code>codebase-gradle</code>, 문서화된`.agents/sessions/`내 에이거/레이즈/핫/워머/콜드 에이전트 거버넌스 방법론에 따라. 인용된 기술 출처는 HuggingFace와 arXiv에서 공개적으로 이용 가능합니다.</strong></p> </div> </div> </div> https://cheroliv.com/blog/2026/0111_audit_contexte_agent_post.html Mon, 27 Apr 2026 00:00:00 +0000 blog/2026/0111_audit_contexte_agent_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_장면_세션_051_뭔가_이상해">장면: 세션 051, 뭔가 이상해</a></li> <li><a href="#_감사_627줄_분석하기">감사: 627줄 분석하기</a></li> <li><a href="#_공학을_잃는_두려움">공학을 잃는 두려움</a></li> <li><a href="#_해결책_분할_백과사전">해결책: 분할 백과사전</a></li> <li><a href="#_essentials_파일의_내용">ESSENTIALS 파일의 내용</a></li> <li><a href="#_결과_eager_컨텍스트_50">결과: EAGER 컨텍스트 -50%</a></li> <li><a href="#_왜_폴더_이름이_encyclopedies">왜 폴더 이름이 `encyclopedies/</a></li> <li><a href="#_시리즈의_논리적_연속">시리즈의 논리적 연속</a></li> <li><a href="#_내가_다르게_했더라면">내가 다르게 했더라면</a></li> <li><a href="#_자신의_컨텍스트를_감사하는_가이드">자신의 컨텍스트를 감사하는 가이드</a></li> <li><a href="#_살아_있는_거버넌스">살아 있는 거버넌스</a></li> <li><a href="#_링크">링크</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽기 시간 : 14 minutes</div> <p>몇 주를 보내며 완벽한 에이전트 거버넌스를 구축했습니다. Eager/Lazy, 세션 종료 절차, 순환 백업. 시스템이 가동 중입니다. 그러던 어느 날, 에이전트가 느려졌습니다. 응답이 희석되었습니다. 측정 결과: 자동으로 로드된 1414줄. 그리고 가장 나쁜 점은, 원인이 코드가 아니며, 백로그도 아니며, 세션 아카이브도 아니라는 것입니다. 원인은 당신의 방법을 문서화한 파일입니다.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">두드리는 소리</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_장면_세션_051_뭔가_이상해">장면: 세션 051, 뭔가 이상해</h2> <div class="sectionbody"> <div class="paragraph"> <p>2026년 4월 30일, 16시 00분. 저는 현재 진행 중인 세션에서`magic-stick`, 내 프로젝트의 Linux 라이브 ISO 빌드. Opencode 에이전트가 평소처럼 자동으로 내 Eager 파일들을 로드했어요 —<code>AGENT.adoc</code>, <code>PROMPT_REPRISE.adoc</code>, `.agents/INDEX.adoc`모든 것이 정상입니다.</p> </div> <div class="paragraph"> <p>하지만 답변이 미지근해. 에이전트는 추론에 두 초 더 걸린다. 그는 세 메시지 전에 눈앞에 있던 세부 사항을 잊어버린다. 이는 충돌도 오류도 아닌 — 서서히 나빠지는 현상, 바로 눈치채지 못하는 종류다.</p> </div> <div class="paragraph"> <p>이미 세션 048에서 그런 상황을 경험한 적이 있었는데, 그때 지배 파일들이 누적으로 5200줄에 달한다는 사실을 알게 되었습니다. 그러고 나서 10세션 슬라이딩 윈도우를 가진 Hot/Warm/Cold 메커니즘, 동일한 냉각 파동, 두 트리거를 가진 센서를 개념화했습니다. 문제는 해결되었다. 이론상으로는.</p> </div> <div class="paragraph"> <p>하지만 여기, 우리는 세션 051에 있다. 백업 회전이 정상적으로 이루어졌다 — EAGER 파일은 2087줄에서 500줄로 줄었다. 그런데 상황은 여전히 무겁다. 뭔가 놓치고 있는 것 같다.</p> </div> <div class="paragraph"> <p>터미널을 열고 입력합니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">wc -l AGENT.adoc AGENT_MODUS_OPERANDI.adoc PROMPT_REPRISE.adoc \ .agents/INDEX.adoc .agents/SESSIONS_HISTORY.adoc \ .agents/archives/COMPLETED_TASKS_ARCHIVE_2026-04.adoc</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs"> 287 AGENT.adoc 627 AGENT_MODUS_OPERANDI.adoc 51 PROMPT_REPRISE.adoc 218 .agents/INDEX.adoc 18 .agents/SESSIONS_HISTORY.adoc 213 .agents/archives/COMPLETED_TASKS_ARCHIVE_2026-04.adoc 1414 total</code></pre> </div> </div> <div class="paragraph"> <p>1414줄. 백업 로테이션이 INDEX, SESSIONS_HISTORY, COMPLETED_TASKS를 깔끔하게 정리했습니다 — 이들은 깨끗합니다. 하지만 방 안에 코끼리가 있는데 내가 보지 못했어 :<strong>627줄</strong>한 파일에`AGENT_MODUS_OPERANDI.adoc`.</p> </div> <div class="paragraph"> <p>이 파일은 내가 세션 1에서 Eager/Lazy 전략을 문서화하기 위해 쓴 파일입니다. 이것은 방법의 매뉴얼입니다. 그리고 이것은 단독으로 EAGER 컨텍스트의 44%가 되었습니다.</p> </div> <div id="diag-before-audit" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE title 컨텍스트 EAGER — 1414줄 rectangle "AGENT_MODUS_OPERANDI **627줄 (44%)**" as MOD #FFCDD2 rectangle "AGENT.adoc\n287 줄 (20%)" as AG #BBDEFB rectangle "INDEX.adoc 218줄 (15%)" as IDX #C8E6C9 rectangle "COMPLETED_TASKS\n213 줄 (15%)" as ARC #FFF9C4 rectangle "PROMPT_재개 51줄 (4%)" as PRO #E1BEE7 rectangle "SESSIONS_HISTORY 18 줄 (1%)" as HIS #FFE0B2 note bottom of MOD Le fichier qui documente la méthode est devenu le plus gros poste de dépense end note @enduml</pre> </div> </div> <div class="paragraph"> <p>아이러니가 완전하다. <strong>컨텍스트를 절약하기 위해 설계된</strong> 파일이 이제는 *컨텍스트의 주요 소비자*가 되었다. 그것은 마치 당신의 자동차 사용 설명서가 엔진보다 무겁다고 생각하는 것과 같다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_감사_627줄_분석하기">감사: 627줄 분석하기</h2> <div class="sectionbody"> <div class="paragraph"> <p>섹션별로 감사를 진행하기로 결정했습니다. 삭제하기 위해서가 아니라, *이해*하기 위해 EAGER에 있어야 할 것과 다른 곳에 거주해도 지식 손실 없이 살 수 있는 것을 구분하기 위해서입니다.</p> </div> <div class="paragraph"> <p>다음은 정확한 구조의`AGENT_MODUS_OPERANDI.adoc`그리고 내가 거기서 찾는 것 :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2739%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">섹션</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">라인</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">내용</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">이미 존재하는…​</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P1 — 개요</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">64</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">문제 해결, 기본 원칙, 대시보드와 매뉴얼의 비유</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(No source text provided, so nothing to translate.)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P2 — 파일 구조</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">97</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">트리 구조, 로딩 정책, 언제 무엇을 로드할지</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P3 — 절대 규칙</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">34</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Git 금지, 파괴적인 명령어 금지, 비밀 금지</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>AGENT.adoc</code>+<code>INDEX.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P4 — 세션 생명 주기</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">133</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">템플릿 개시, 작업 규칙, 6단계 세션 종료, 체크리스트</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>AGENT.adoc</code>§종료 세션 +<code>INDEX.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P5 — 메트릭스와 임계값</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">49</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">이상적인 세션 (15-30분, 1-3 파일), 경고 신호</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P6 — 세션 유형</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">72</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">탐지 표, 제안 형식, 예외</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P7 — 지속적인 개선</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">39</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">추적 지표, 주간 리뷰</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P8 — 시작 체크리스트</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">13</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Bootstrap 새 프로젝트</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P9 — 참고문헌</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">30</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">참조 파일, 외부 리소스</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>AGENT.adoc</code>(파일 EAGER/LAZY)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>부록 A+B</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">42</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">용어 사전, 버전 기록</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>판결은 최종적 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>완전한 중복</strong>(167 줄) : P3, P4, P9 — 모든 것이 이미 안에 있다`AGENT.adoc` ou <code>INDEX.adoc</code>, 자주 단어 그대로</p> </li> <li> <p><strong>실전에서 assoluta 참조된 적이 없음</strong>(215 줄) : P5, P6, P7, P8, 부록 — 메타 거버넌스가 어느 세션에서도 사용된 적이 없는</p> </li> <li> <p><strong>유일한 지식</strong>(161 lignes) : P1과 P2 — 어휘 LAZY/EAGER, 비유, 로딩 정책</p> </li> </ul> </div> <div class="paragraph"> <p>627줄에<strong>382는 소음</strong>. 이 382줄은 <strong>세션 시작 시마다</strong> 로드되고, 에이전트에 의해 소비되며, 내가 인사도 하기 전에 그의 주의를 희석시킵니다.</p> </div> <div id="diag-audit-result" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title AGENT_MODUS_OPERANDI.adoc 감사 — 627 줄 left to right direction rectangle "🟡 **중복**\n167줄 (27%)" as DUP #FFF9C4 { card "P3 — 절대 규칙 (34 줄)" as D1 card "P4 — 생명 주기 (133 줄)" as D2 card "P9―참고문헌 (30줄)" as D3 } rectangle "🔴 **절대 확인되지 않음** 215줄 (34%)" as JAM #FFCDD2 { card "P5 — 메트릭 (49 줄)" as J1 card "P6 — 탐지 (72줄)" as J2 card "P7 — 개선 (39줄)" as J3 card "P8 — Bootstrap (13줄)" as J4 card "부록 — 용어집 (42 줄)" as J5 } rectangle "🟢 **유일한 지식** 161줄 (26%)" as UNI #C8E6C9 { card "P1 — 개요 (64줄)" as U1 card "P2 — 파일 구조 (97 줄)" as U2 } note bottom of UNI C'est ÇA qu'il faut garder en EAGER. Le reste → cold storage. end note @enduml</pre> </div> </div> <div class="paragraph"> <p>이 다이어그램이 모든 것의 핵심이다. 중복(노란색)은 순수한 노이즈이다 — 에이전트가 이를 두 번 읽으며, 두 개의 다른 파일에서이다. 절대 참조되지 않은 (빨간색)은死んだ 문서이다 — 주의 깊게 작성되었지만 결코 사용되지 않았다. 오직 초록색만이 에이전트가 다른 곳에서 찾을 수 없는 지식을 포함한다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_공학을_잃는_두려움">공학을 잃는 두려움</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 시점에서, 저는 증거를 눈앞에 두고 있습니다: 저는 줄여야 합니다.<code>AGENT_MODUS_OPERANDI.adoc</code>. 하지만 주저해요.</p> </div> <div class="paragraph"> <p>이 파일은 손으로 썼습니다. 각 섹션은 실제 세션에서 배운 교훈의 결과입니다. P3 부분은 …​에서 태어났다.`rm -rf`우발적인 위에`bakery-plugin`실제 Firebase 토큰이 소모되었습니다. P4 부분은 아카이빙을 잊고 흐름을 잃은 15번의 세션 결과입니다. 6단계 절차는 책에서 나온 것이 아니라 고통에서 나온 것이다.</p> </div> <div class="paragraph"> <p>이 섹션들을 삭제하는 것은 내 자신의 엔지니어링 역사를 버리는 것과 같다. 이들로부터 생긴 교훈들, 내가 그들을 발견했던 세션들, 다시는 되풀이하고 싶지 않은 오류들. 이것은 텍스트가 아니라 — 결정화된 경험이다.</p> </div> <div class="paragraph"> <p>여기에 내가 해결책을 안내하는 원칙을 제시한다:</p> </div> <div class="paragraph"> <p><em><em>_ <strong>절대 삭제하지 마십시오. 항상 재배치하십시오.</strong>지식은 프로젝트에서 사라질 필요가 없습니다. 그저 필요하지 않을 때 자동으로 로드되지 않으면 됩니다. </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_해결책_분할_백과사전">해결책: 분할 백과사전</h2> <div class="sectionbody"> <div class="paragraph"> <p>제가 제안하는 모델은 간단하며 위키피디아가 성장한 방식에서 영감을 얻었습니다: 기사가 너무 길어지면 잘라내지 않고 — 상세한 기사를 작성하고 메인 기사에 요약을 유지합니다.</p> </div> <div class="paragraph"> <p>를 위해`AGENT_MODUS_OPERANDI.adoc`, 그 결과는 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>추출하다</strong>161개의 고유한 지식 라인 (P1 + P2)를 새로운 파일에`LAZY_EAGER_ESSENTIALS.adoc`— 약 50줄로 압축, 엄격히 EAGER</p> </li> <li> <p><strong>이름 바꾸기</strong> <code>AGENT_MODUS_OPERANDI.adoc</code> en <code>.agents/encyclopedies/LAZY_EAGER_ENCYCLOPEDIE.adoc</code>— 원래 627줄 파일, <strong>손상되지 않은</strong> 상태로, 콜드 스토리지에</p> </li> <li> <p><strong>절대로 충전하지 마</strong>encyclopedia 파일을 자동으로 — 인간을 위해 존재하며, 미래의 증류를 위해, 그리고 6개월 후에 더 나은 모델로 호출할 에이전트를 위해 존재합니다</p> </li> </ol> </div> <div id="diag-split-solution" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title 분할된 백과사전 — AGENT_MODUS_OPERANDI left to right direction rectangle "**AGENT_MODUS_OPERANDI.adoc** 627줄 (분할 전)" as BEFORE #FFCDD2 { } rectangle " " as ARROW1 rectangle " " as ARROW2 rectangle "**LAZY_EAGER_ESSENTIALS.adoc**\n**~50줄 — EAGER**" as ESS #C8E6C9 { card "P1 압축된 (15줄)" as E1 card "P2 압축된 (35줄)" as E2 } rectangle ".agents/encyclopedies/** **LAZY_EAGER_ENCYCLOPEDIE.adoc** 627줄 — COLD" as ENC #BBDEFB { card "P1부터 부록까지 (완전하고 손상되지 않은)" as C1 } BEFORE -[#4CAF50]-> ESS : "추출의 비판적 지식" BEFORE -[#2196F3]-> ENC : "완전한 보존 공학의" note bottom of ESS Chargé automatiquement en début de session → L'agent comprend le vocabulaire end note note bottom of ENC Jamais chargé automatiquement Consultable par l'humain Matériau brut pour distillation future end note @enduml</pre> </div> </div> <div class="paragraph"> <p>이름`encyclopedies/`그것은 우연이 아닙니다. 백과사전은 아카이브 파일이 아니라 — 조직화된 지식의 집합체이며, 조회할 수 있지만 휴대할 수 없습니다. 지하철에서는 Universalis 백과사전을 읽지 않습니다. 우리는 그것을 도서관에 보관하고, 특정한 질문이 있을 때 거기에 가서 찾습니다.</p> </div> <div class="paragraph"> <p>이것이 바로 이 폴더의 역할입니다: 차가운, 구조화되고 포괄적인 참조 라이브러리 — 에이전트가 자동으로 건드리지 않는</p> </div> </div> </div> <div class="sect1"> <h2 id="_essentials_파일의_내용">ESSENTIALS 파일의 내용</h2> <div class="sectionbody"> <div class="paragraph"> <p>여기서 새 파일이 구체적으로 어떻게 보이는지입니다.<code>LAZY_EAGER_ESSENTIALS.adoc</code>, 추출 및 압축된 P1과 P2에서 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Stratégie LAZY/EAGER — Principes Essentiels [abstract] Ce fichier définit la stratégie de gestion du contexte agent. Chargé automatiquement (EAGER) en début de session. == Principes |=== | EAGER | LAZY | Tableau de bord | Manuel du propriétaire | Chargé automatiquement | Chargé sur demande | <= 100 lignes, <= 10k tokens | Illimité, détaillé | Règles absolues, mission courante | Archives, historique, références |=== == Politique de Chargement |=== | Fichier | Type | Quand charger | PROMPT_REPRISE.adoc | EAGER | Début session (auto) | *_ESSENTIALS.adoc | EAGER | Début session si EPIC active | .agents/INDEX.adoc | EAGER | Début session (auto) | *_REFERENCE.adoc | LAZY | Sur besoin (détails architecture) | .agents/sessions/N-*.adoc | LAZY | Sur demande (détails session) | .agents/encyclopedies/*.adoc | COLD | Jamais auto (humain seulement) |=== == Comment l'Agent Sait Quoi Charger Début session → PROMPT_REPRISE + INDEX + ESSENTIALS actifs. Besoin de détails → charger les *_REFERENCE et sessions/ en LAZY. Connaissance froide → encyclopedies/, jamais automatique.</code></pre> </div> </div> <div class="paragraph"> <p>오십 줄. 에이전트가 메커니즘을 이해하기 위해 필요한 것은 이것뿐이다. 나머지는 — 수업 기록, 상세한 비유, 단계별 절차, 부록 — 모두 백과사전에 있다.</p> </div> <div class="paragraph"> <p>그리고 가장 중요한 것:<strong>아무것도 삭제되지 않았습니다.</strong>. 627개의 엔지니어링 라인이 여전히 여기에 있습니다, 안에`.agents/encyclopedies/LAZY_EAGER_ENCYCLOPEDIE.adoc`. 그들은 단지 도서관에 정리되어 있을 뿐, 작업대 위에 놓여 있지 않다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_결과_eager_컨텍스트_50">결과: EAGER 컨텍스트 -50%</h2> <div class="sectionbody"> <div class="paragraph"> <p>분할 전:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs"> 287 AGENT.adoc 627 AGENT_MODUS_OPERANDI.adoc 51 PROMPT_REPRISE.adoc 218 .agents/INDEX.adoc 18 .agents/SESSIONS_HISTORY.adoc 213 .agents/archives/COMPLETED_TASKS_ARCHIVE_2026-04.adoc 1414 total</code></pre> </div> </div> <div class="paragraph"> <p>분할 후 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs"> 287 AGENT.adoc 50 LAZY_EAGER_ESSENTIALS.adoc ← remplace 627 lignes 51 PROMPT_REPRISE.adoc 218 .agents/INDEX.adoc 18 .agents/SESSIONS_HISTORY.adoc 213 .agents/archives/COMPLETED_TASKS_ARCHIVE_2026-04.adoc 837 total ← -41%</code></pre> </div> </div> <div id="diag-after-audit" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE title 백과사전 분할 이후 EAGER 컨텍스트 — 837줄 (-41%) rectangle "AGENT.adoc\n287줄 (34%)" as AG #BBDEFB rectangle "INDEX.adoc 218 줄 (26%)" as IDX #C8E6C9 rectangle "COMPLETED_TASKS\n213 줄 (25%)" as ARC #FFF9C4 rectangle "PROMPT_REPRISE 51줄 (6%)" as PRO #E1BEE7 rectangle "필수 50줄 (6%)" as ESS #A5D6A7 rectangle "SESSIONS_HISTORY\n18 줄 (2%)" as HIS #FFE0B2 note bottom of ESS De 627 → 50 lignes 577 lignes d'ingénierie préservées en cold storage Rien de perdu. Tout de relocalisé. end note @enduml</pre> </div> </div> <div class="paragraph"> <p>가장 큰 소비자 (AGENT_MODUS_OPERANDI, 627줄)가 50줄 파일로 대체되었습니다. 이득은 즉각적이며: 577줄의 컨텍스트가 해제되었습니다. 에이전트가 숨을 쉰다.</p> </div> <div class="paragraph"> <p>그리고 안에`.agents/encyclopedies/`, 원본 파일에 627줄이 기다리고 있습니다. 변함없이. 모든 섹션과 함께 — 중복된 섹션도 포함하고, 한 번도 사용되지 않은 섹션도 포함해서. 어느 날, 더 나은 모델이나 인간 데이터 과학자가 이러한 각도, 가정되는 중복, 배운 교훈을 교차하고 싶어하기 때문입니다. 그날에는 원본 데이터가 있을 것이다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_왜_폴더_이름이_encyclopedies">왜 폴더 이름이 `encyclopedies/</h2> <div class="sectionbody"> <div class="paragraph"> <p>이름 선택은 장식이 아닙니다. 그것은 메커니즘의 철학을 인코딩합니다.</p> </div> <div class="paragraph"> <p>하나의 <strong>아카이브</strong> (<code>archives/`포함합니다 연대순으로 정리된 과거 데이터 — 월별 COMPLETED_TASKS처럼. 하나의 <strong>backup</strong> (`backup/</code>) 는 타임스탬프가 붙은 스냅샷입니다 — 과거 상태의 백업 사본입니다.</p> </div> <div class="paragraph"> <p><strong>백과사전</strong>, 그것은 다른 것입니다. 주제별 지식의 컬렉션으로, 주제에 따라 구조화되어 있고 포괄적이지만 선형적이지 않습니다. 백과사전을 처음부터 끝까지 읽지 않습니다. 구체적인 질문에 답하기 위해 그곳에 뛰어듭니다.</p> </div> <div class="paragraph"> <p>이것은 정확히 이 파일의 계약입니다 :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">폴더</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">역할</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">접근</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">세분도</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>archives/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">역사적 데이터 (월별 완료된 작업)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">게으른, 구조화된</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">연대순의</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>backup/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">차가운 스냅샷 (10세션 물결)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">콜드, 전체 복사</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">연대순</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>encyclopedies/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">주제에 대한 포괄적인 지식 (방법론, 패턴)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">COLD, 자동이 아님</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">주제</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>이 구분은 잡탕을 피합니다. 각 파일은 *무엇을 포함하는지*에 따라 어디에 있어야 하는지를 알고, *언제 만들어졌는지*에 따라 결정되지 않습니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_시리즈의_논리적_연속">시리즈의 논리적 연속</h2> <div class="sectionbody"> <div class="paragraph"> <p>첫 두 개의 기사를 읽으셨다면, 다음은 세 조각이 어떻게 맞물리는지 보여 드리겠습니다 :</p> </div> <div id="diag-trilogie" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 220 title 에이전트 거버넌스 삼부작 left to right direction package "📖 **Article 0108** 전략 Eager/Lazy" as A1 #E8F5E9 { card "메모리 에이전트 세션 간" as M1 card "EAGER 파일 (자동 로드됨)" as M2 card "LAZY 파일 (요청 시)" as M3 card "6단계 절차" as M4 } package "🧊 **Article 0110** 핫/웜/콜드 메커니즘" as A2 #FFF9C4 { card "노화 컨텍스트의" as V1 card "슬라이딩 윈도우 10 세션" as V2 card "차가운 파도 동일한" as V3 card "센서와\n두 개의 트리거" as V4 } package "🔍 **Article 0111** 감사 + 백과사전 솔루션" as A3 #BBDEFB { card "파일 감사 EAGER" as E1 card "식별 폐기물" as E2 card "Split 필수/백과사전" as E3 card "엔지니어링 보존" as E4 } A1 --> A2 : "메모리가 커집니다 → 노화 메커니즘이 필요합니다" A2 --> A3 : "노화만으로는 부족합니다 → EAGER에 있어야 할 것을 감사해야 합니다" note bottom of A3 ✅ Les trois couches sont en place sur 6 projets actifs end note @enduml</pre> </div> </div> <div class="ulist"> <ul> <li> <p><strong>0108</strong>답변: « 에이전트에게 두 세션 사이에 메모리를 어떻게 줄 수 있나요?</p> </li> <li> <p><strong>0110</strong>답변 : « 이 기억이 에이전트를 질식시키는 것을 어떻게 막을 수 있나요?</p> </li> <li> <p><strong>0111</strong> 답변 : « 그리고 문제가 아카이브의 크기가 아니라 우리가 *선택*하여 EAGER에 넣은 것이라면? »</p> </li> </ul> </div> <div class="paragraph"> <p>첫 번째 논문은 구조를 구축했다. 두 번째 논문은 노화 메커니즘을 추가했다. 세 번째 논문은 내용을 감사하고 — 방법론 자체가 문제라는 것을 발견한다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_내가_다르게_했더라면">내가 다르게 했더라면</h2> <div class="sectionbody"> <div class="paragraph"> <p>돌이켜보면, 처음 설계의 오류를 보입니다.`AGENT_MODUS_OPERANDI.adoc`이는 단일 문서로 만들어졌으며 — 하나의 선언문이었습니다. 이는 생각을 형식화하는 데 올바른 접근 방식이었습니다. 하지만 생각이 형식화된 후에는 문서를 즉시 분할해야 했습니다: 핵심은 EAGER에, 포괄적인 내용은 cold에 두어야 했습니다.</p> </div> <div class="paragraph"> <p>나는 문서에 자랑스러워서 그것을 하지 않았다. 627줄의 순수 공학, 손으로 쓴 것이며, 각 부분은 세션 수업의 결과물이다. 그것은 나의 작품이었다. 그리고 모든 작가처럼, 나는 그것을 자르는 데 어려움을 겪었다.</p> </div> <div class="paragraph"> <p>수업:<strong>문서가 좋다고 해서 자동으로 로드되어야 하는 것은 아니다.</strong>. 콘텐츠의 품질은 에이전트의 즉각적인 상황과 관련이 없습니다.</p> </div> <div class="paragraph"> <p>오늘, 규칙은 간단합니다: EAGER 컨텍스트에서 100줄이 넘는 문서는 모두 의심 대상입니다. 감사를 받아야 합니다. 처벌이 아니라 감사입니다. 그리고 질문은 결코 '삭제해야 하는가?'가 아니라 '매 세션마다 로드해야 하는가?'입니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_자신의_컨텍스트를_감사하는_가이드">자신의 컨텍스트를 감사하는 가이드</h2> <div class="sectionbody"> <div class="paragraph"> <p>첫 번째와 두 번째 기사를 따르고 자체적인 Eager/Lazy 거버넌스를 구축했다면, 여기 5단계 감사 절차가 있습니다:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>측정</strong> : `wc -l`모든 EAGER 파일에. 총 수는 1000줄 미만이어야 합니다.</p> </li> <li> <p><strong>가장 큰 것 식별</strong>: 전체 용량의 20%보다 큰 파일이 첫 번째 용의자입니다.</p> </li> <li> <p><strong>섹션별로 감사하기</strong>: 각 섹션마다 자신에게 묻습니다. « 이 정보가 이미 다른 곳에 있나요? 해당 대리인이 이미 다른 파일에서 이를 읽었나요? 이 정보가 지난 5번의 세션에서 사용되었나요?</p> </li> <li> <p><strong>분류기</strong>: 중복, 절대 사용되지 않음, 고유한 지식.</p> </li> <li> <p><strong>분할하거나 재배치</strong>: 고유하고 중요한 것 → ESSENTIALS 압축된. 그 외의 모든 것 →<code>encyclopedies/</code>.</p> </li> </ol> </div> <div id="diag-audit-checklist" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title 에이전트 컨텍스트 감사 절차 — 5단계 start :1. **Mesurer**\n`wc -l *.adoc .agents/*.adoc`; if (Total > 1000 lignes ?) then (oui) :⚠️ Contexte trop lourd; else (non) :✅ Contexte OK; stop endif :2. **Identifier le suspect**\nLe fichier > 20% du total; :3. **Auditer section par section**\nPour chaque section :\n• Déjà ailleurs ? → doublon\n• Jamais servi ? → mort\n• Information unique ? → critique; :4. **Classifier**\n🟡 Doublons → à retirer de l'EAGER\n🔴 Jamais utilisé → cold storage\n🟢 Connaissance unique → à garder; :5. **Splitter**\n🟢 → ESSENTIALS (~50 lignes, EAGER)\n🟡🔴 → encyclopedies/ (cold storage); :✅ Contexte optimisé\nsans perte d'ingénierie; stop @enduml</pre> </div> </div> <div class="paragraph"> <p>이 절차는 15분이 소요됩니다. 50세션 프로젝트에서는 향후 세션당 수백 토큰을 절약하며, ROI는 즉시 발생합니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_살아_있는_거버넌스">살아 있는 거버넌스</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 세 글 시리즈에서 배운 것은 에이전트 거버넌스가 완성된 제품이 아니라는 것입니다. 이것은<strong>살아있는 유기체</strong>. 그녀는 프로젝트와 함께 성장합니다. 그녀는 성장 관련 질병에 걸립니다. 그녀는 정기적인 검진이 필요합니다.</p> </div> <div class="paragraph"> <p>세션 048은 아카이브가 부풀어 오르고 있음을 드러냈다. 세션 051은 방법론 자체가 부풀어 오르고 있음을 드러냈다. 세션 060은 아마도 다른 것을 드러낼 것이다. 정상이다. 건강하다. 자신을 결코 의심하지 않는 통치는 죽은 통치이다.</p> </div> <div class="paragraph"> <p>설정된 세 가지 메커니즘 — Eager/Lazy, Hot/Warm/Cold, 백과사전식 분할 — 은 맥락 포화에 대한 심층 방어 체계를 형성합니다. 단독으로는 충분하지 않습니다. 함께 사용하면 서로 보완됩니다:</p> </div> <div class="ulist"> <ul> <li> <p><strong>즉시/지연</strong>정보를 <strong>가용성별로</strong> 구조화하다</p> </li> <li> <p><strong>뜨거운/따뜻한/차가운</strong>정보를 <strong>신선도</strong> 순으로 구조화</p> </li> <li> <p><strong>백과사전식 감사</strong>정보 구조화 <strong>밀도별로</strong></p> </li> </ul> </div> <div id="diag-defense-in-depth" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam nodeBackgroundColor #E3F2FD title 컨텍스트 포화에 대한 깊이 있는 방어 node "**컨텍스트 에이전트** ~800 줄 건전한" as CTX #C8E6C9 node "층 1 **EAGER / LAZY**" as C1 #BBDEFB node "레이어 2 **더운 / 따뜻한 / 추운**" as C2 #BBDEFB node "3층 **필수 / 백과사전**" as C3 #BBDEFB CTX --> C1 : "구조별\n**가용성**" CTX --> C2 : "구조는 **신선함**" CTX --> C3 : "구조에 따른\n**밀도**" note bottom of C3 Les trois couches sont nécessaires. Aucune n'est suffisante seule. end note @enduml</pre> </div> </div> <div class="paragraph"> <p>이 세 층으로, 에이전트 컨텍스트가`magic-stick`2087줄(최적화 이전)에서 약 800줄로 줄어들어 — 2.6배로 감소했습니다. 문서 한 줄도, 세션 아카이브 하나도, 배운 교훈 하나도 잃지 않았습니다.</p> </div> <div class="paragraph"> <p>모든 것이 거기에 있다. 그저 더 잘 정리되어 있다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_링크">링크</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Article 0108 — Eager/Lazy 전략 :<a href="/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html">AsciiDoc로 AI 에이전트 관리하기</a></p> </li> <li> <p>Article 0110 — Hot/Warm/Cold 메커니즘 :<a href="/blog/2026/0110_mecanisme_backup_contexte_agent_post.html">Sliding Window과 차가운 파도</a></p> </li> <li> <p>내 사이트 : <a href="https://cheroliv.com" class="bare">https://cheroliv.com</a></p> </li> <li> <p>프로젝트`magic-stick`: <a href="https://github.com/cheroliv/magic-stick" class="bare">https://github.com/cheroliv/magic-stick</a></p> </li> </ul> </div> <hr> <div class="paragraph"> <p><strong>지식은 사라질 필요가 없습니다. 그것은 필요하지 않을 때는 단순히 로드되지 않아도 됩니다.</strong></p> </div> </div> </div> https://cheroliv.com/blog/2026/0110_mecanisme_backup_contexte_agent_post.html Sun, 26 Apr 2026 00:00:00 +0000 blog/2026/0110_mecanisme_backup_contexte_agent_post.html <div class="sect1"> <h2 id="_요약">요약</h2> <div class="sectionbody"> <div class="paragraph"> <p>단일 프로젝트에 대해 48회 세션을 진행하고 전체적으로 150+회를 한 후, 내가 신중히 구축한 Eager/Lazy 거버넌스 시스템이 답답해지기 시작했다. 가벼워야 할 에이전트 파일들이 누적 5200줄에 달했다. 자동으로 로드되는 컨텍스트는 내가 제어할 수 있는 속도보다 빠르게 증가했다. 이 글에서는 활성 컨텍스트를 가볍게 유지하면서도 절대 손실을 입히지 않도록, 슬라이딩 윈도우와 동일한 콜드 웨이브 사이에 위치한 백업 메커니즘을 어떻게 개념화했는지 설명한다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_시그널_5200_줄">시그널: 5200 줄</h2> <div class="sectionbody"> <div class="paragraph"> <p>저는 현재 세션 048 중이에요`magic-stick`, 내 Linux 라이브 ISO 빌드 프로젝트. Opencode가 나를 바라보고 있다. 항상처럼, 그것은 세션 시작時に 내 Eager 파일을 자동으로 로드했다 —<code>AGENT.adoc</code>, <code>PROMPT_REPRISE.adoc</code>, <code>.agents/INDEX.adoc</code>. 별일 없습니다.</p> </div> <div class="paragraph"> <p>그런데 뭔가 잘못됐다. 답변이 더 느려진다. 추론이 더 희석된다. 에이전트는 몇 메시지 전에 눈앞에 있던 세부 사항을 잊어버린다.</p> </div> <div class="paragraph"> <p>터미널을 열고 입력합니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">wc -l .agents/INDEX.adoc .agents/SESSIONS_HISTORY.adoc \ .agents/archives/COMPLETED_TASKS_ARCHIVE_2026-04.adoc</code></pre> </div> </div> <div class="paragraph"> <p>INDEX용 260줄. SESSIONS_HISTORY용 55줄.<strong>1756 COMPLETED_TASKS_ARCHIVE용</strong>.</p> </div> <div class="paragraph"> <p>폴더`sessions/`또 약 3200줄을 추가합니다. 전체 :<strong>5200줄</strong>컨텍스트가 로드되는, 한 가지 방식이든 다른 방식이든, 에이전트의 일시적인 두뇌에.</p> </div> <div class="paragraph"> <p>이전 기사에서 내가 이론화한 Eager/Lazy 전략은 작동한다 — 하지만 그녀가 예상하지 못한 탄생 결함이 있다 : 그녀는 없다<strong>노화 메커니즘이 없습니다.</strong>. 각 세션은 INDEX에 한 줄을 추가합니다, COMPLETED_TASKS에 한 단락을 추가합니다, sessions/ 폴더에 하나의 파일을 추가합니다. 아무것도 절대 나오지 않습니다. 컨텍스트는 매 새로운 세션마다 커지는 눈덩이와 같습니다.</p> </div> <div id="diag-growth" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam handwritten false title 컨텍스트 에이전트 성장 — 세션 1에서 48까지 rectangle "세션 1-10" as S10 #E8F5E9 rectangle "세션 11-20" as S20 #C8E6C9 rectangle "세션 21-30" as S30 #A5D6A7 rectangle "세션 31-40" as S40 #81C784 rectangle "세션 41-48" as S48 #66BB6A note right of S10 INDEX : ~50 lignes SESSIONS : ~10 lignes ARCHIVE : ~100 lignes **Total : ~300 lignes** end note note right of S20 INDEX : ~100 lignes SESSIONS : ~20 lignes ARCHIVE : ~400 lignes **Total : ~800 lignes** end note note right of S30 INDEX : ~160 lignes SESSIONS : ~30 lignes ARCHIVE : ~900 lignes **Total : ~1800 lignes** end note note right of S40 INDEX : ~220 lignes SESSIONS : ~45 lignes ARCHIVE : ~1400 lignes **Total : ~3200 lignes** end note note right of S48 INDEX : **260 lignes** SESSIONS : **55 lignes** ARCHIVE : **1756 lignes** **Total : 5200 lignes** ⚠️ end note S10 -[#green]-> S20 S20 -[#green]-> S30 S30 -[#FF9800]-> S40 S40 -[#red]-> S48 @enduml</pre> </div> </div> <div class="paragraph"> <p>이건 버그가 아니라 세션 종료 절차의 직접적인 결과입니다. 이 절차는 세부 사항을 하나하나 꼼꼼히 보관합니다. 시스템은 자신의 성공의 희생자입니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_진단_삼중_중복">진단 : 삼중 중복</h2> <div class="sectionbody"> <div class="paragraph"> <p>나는 요원에게 문제를 진단해 달라고 요청한다. 그의 답변은 외과적이고 즉각적이다.</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">파일</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">줄</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">역할</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">문제</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.agents/INDEX.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">260+</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">열정적 (자동 충전)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">001부터의 모든 세션 테이블 —<strong>+1 줄당 세션</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.agents/SESSIONS_HISTORY.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">55</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">열망하는</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">요약 표 —<strong>INDEX와의 중복</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>COMPLETED_TASKS_ARCHIVE_2026-04.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1756</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">열망 (묵시적)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">4월 모든 세션의 상세 내용</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.agents/sessions/*.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~5200 total</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">게으른 (추정되는)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">개인 기록 보관소, 하지만<strong>사용되지 않은</strong>왜냐하면 모든 것이 이미 COMPLETED_TASKS에 있습니다.</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>에이전트는 네 가지 근본 원인을 식별한다 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>COMPLETED_TASKS_ARCHIVE 모든 것을 흡수합니다</strong>— 아카이브를 가리키는 대신`.sessions/`, 그는 각 세션을 완전히 복사합니다.</p> </li> <li> <p><strong>INDEX.adoc는 완전한 기록으로 기능합니다.</strong>— 표 "Sessions Récentes"에는 30+개의 항목이 있습니다.</p> </li> <li> <p><strong>SESSIONS_HISTORY.adoc 중복</strong>— 같은 정보가 INDEX이고, 형식이 다릅니다.</p> </li> <li> <p><strong>LAZY 규칙이 준수되지 않았습니다.</strong>— COMPLETED_TASKS는 모든 것을 포함하기 때문에 암시적으로 EAGER입니다.</p> </li> </ol> </div> <div class="paragraph"> <p>INDEX`를 10세션으로 제한, `COMPLETED_TASKS`를 비우다, `SESSIONS_HISTORY`를 순수한 LAZY로 이동. 즉시 얻을 수 있는 이득 :<strong>~1900줄 절감</strong>.</p> </div> <div class="paragraph"> <p>깨끗하고 효율적이며 논리적입니다. 하지만 저는 이 접근 방식에 문제가 있습니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_왜_나는_명백한_해결책을_거절한_걸까">왜 나는 명백한 해결책을 거절한 걸까?</h2> <div class="sectionbody"> <div class="paragraph"> <p>에이전트의 해결책은 캐시를 최적화하는 엔지니어의 것과 같다. 제한. 자르기. 중복 제거.</p> </div> <div class="paragraph"> <p>하지만 이러한 "중복"은 아닙니다. 각 거버넌스 파일은 하나를 포착합니다.<strong>다른 각도</strong>동일한 현실 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>색인</strong>= 매크로 뷰, 실행 대시보드</p> </li> <li> <p><strong>SESSIONS_HISTORY</strong>= 선형 연대순 테이블, 점수가 매겨진</p> </li> <li> <p><strong>완료된 작업 아카이브</strong>= 상세한 서사와 지표</p> </li> <li> <p><strong>sessions/*.adoc</strong> = 개별 아카이브, 전체 컨텍스트</p> </li> </ul> </div> <div class="paragraph"> <p>그건 멍청한 복제가 아닙니다. 그건<strong>다중 구조화된 관점</strong>이것이 정확히 우리가 증류하기 위해 필요한 것이며, 나중에 인간(또는 향후 더 잘 훈련된 LLM)이 각도를 교차하고 패턴을 추출할 수 있도록 하기 위함이다.</p> </div> <div class="paragraph"> <p>데이터 과학자가 당신에게 말한다고 상상해 보세요: « 6개 컬럼 중 3개를 삭제합시다, 이들은 상관관계가 있습니다. » 당신에게 뭐라고 답변하시겠습니까? 상관관계는 각 컬럼이 같은 현상의 서로 다른 차원을 포착할 때 중복이 아닙니다. 바로 이러한 차원의 풍부함이 데이터셋을 사용 가능하게 만드는 것입니다.</p> </div> <div class="paragraph"> <p>이게 나의 직관이다. 그리고 나는 에이전트의 차가운 합리성에 맞서 이를 방어한다.</p> </div> <div class="paragraph"> <p><em><em>_ 내 아이디어에는 조용한 만능 도구가 보이지 않아. 우리는 모든 것을 넣지 않고, 세션 종료 절차의 구조화된 결과를 이동한다 — 각 파일에 그 각도와, 실제로는 풍부하게 하는 중복이 있다. 이것이 다차원적인 자료가 증류에 더 좋을 것이다. </em>_</em></p> </div> <div class="paragraph"> <p>에이전트는 충격을 받는다. 그리고 스스로를 바로잡는다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_제안_동일한_추위_파도">제안 : 동일한 추위 파도</h2> <div class="sectionbody"> <div class="paragraph"> <p>에이전트는 그 후 더 정교한 메커니즘을 제안합니다. 이는 풍부한 데이터셋에 대한 직관을 존중하면서도, 폭발하는 컨텍스트 문제를 해결하는 기술적 문제를 해결합니다.</p> </div> <div class="paragraph"> <p>원칙은 간단하며 직접적으로 패턴에서 영감을 얻습니다.<strong>뜨거운/따뜻한/차가운 저장소</strong>아카이브 관리에 적용된 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>뜨거운 (열망하는)</strong>= INDEX 안의 지난 10개의 세션, 세션 N+1의 PROMPT_REPRISE, 마지막 2개의 세션 파일</p> </li> <li> <p><strong>따뜻한 (게으른)</strong>= SESSIONS_HISTORY 최근, SCRIPT_VERIFICATION, 모든 참조 문서</p> </li> <li> <p><strong>콜드 (backup/)</strong>= 나머지 전부, 이동된<strong>손상되지 않은</strong>, 변환 없이, 재인덱싱 없이</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- ---- .agents/ ├── INDEX.adoc → Sessions N-9 à N (10 dernières) ├── SESSIONS_HISTORY.adoc → Sessions N-9 à N ├── SCRIPT_VERIFICATION.adoc → Dernière vérif (pas d'historique) ├── PROMPT_REPRISE.adoc → Session N+1 uniquement ├── sessions/ → Sessions N-1 à N uniquement └── backup/ └── Y2026-sessions-001-039/ ← Vague froide, COPIE INTÉGRALE ├── INDEX.adoc → Sessions 001 à 039 (complet) ├── SESSIONS_HISTORY.adoc → Sessions 001 à 039 (complet) ├── COMPLETED_TASKS_ARCHIVE.adoc → Sessions 001 à 039 (complet) └── sessions/ → 001.adoc, 002.adoc... ---- 메커니즘의 열쇠 :**백업은 중앙 인덱스가 아니라 과거 파도의 정확히 동일한 복사본이다.**. 활성 세션 10을 초과하면 아무것도 삭제하지 않고, 아무것도 재인덱싱하지 않고, 아무것도 병합하지 않습니다. 우리는 N-10 세션 때의 에이전트 파일 패키지를 그대로 취해서 그것을 안으로 이동합니다`backup/`. 활성화된 파일들은 잘립니다: * INDEX : 최근 10줄만 (슬라이딩 윈도우) * SESSIONS_HISTORY : 동일 * COMPLETED_TASKS_ARCHIVE : 현재 기간에 대한 새 파일 * sessions/ : 마지막 2개의 세션만 [plantuml, format=svg, id=diag-hot-warm-cold, alt="Architecture Hot/Warm/Cold du contexte agent — EAGER/LAZY/backup"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 200 title 컨텍스트 에이전트의 핫/웜/콜드 아키텍처 package "HOT (EAGER) 자동으로 충전됨 약 300줄" as HOT #FFCDD2 { file "INDEX.adoc\n(10 세션)" as IDX_HOT file "PROMPT_REPRISE\n(세션 N+1)" as PRO_HOT file "AGENT.adoc (절대 규칙)" as AG_HOT } package "WARM (LAZY) 요청 시 로드 ~500 줄" as WARM #FFF9C4 { file "SESSIONS_HISTORY (최근 10개)" as HIS_WARM file "SCRIPT_VERIFICATION\n(마지막)" as VER_WARM file "PROCEDURES.adoc (템플릿)" as PRO_WARM file "*_REFERENCE.adoc (기술 문서)" as REF_WARM } package "콜드 (backup/) 절대 충전되지 않음 인간 전용 읽기" as COLD #BBDEFB { folder "Y2026-001-039/" as WAVE { file "색인 (완전)" as IDX_COLD file "SESSIONS_HISTORY\n(전체)" as HIS_COLD file "COMPLETED_TASKS\n(완료)" as ARCH_COLD folder "세션/ (001-039)" as SESS_COLD } folder "Y2026-040-??? (future)" as FUTURE } HOT --> WARM : "에이전트가 다시 올라갑니다 필요하면" WARM --> COLD : "절대 자동이 아니다 인간만이 그곳으로 간다" note bottom of COLD Règle : COPIE INTÉGRALE Pas de transformation Pas de réindexation Read-only après archivage end note @enduml ---- 즉시 이익은 엄청납니다 : EAGER 컨텍스트가**~5200줄에서 ~300줄**. 17로 나누기. 역사적 데이터를 한 줄도 잃지 않고. == 왜 이것이 만능이 아닌가 에이전트는 첫 번째 반복에서 두려워했습니다.`backup/`검은 상자가 되는 — 아무도 다시 보지 않을 파일을 버리는 폴더이다. 이는 정당한 두려움이다. 하지만 이는 오해에 기반한다. 잡동사니는 파일을 버릴 때다**구조도 없고, 관례도 없고, 그룹화 논리도 없이**. 여기서는 백업이 기간별(Y2026-001-039)으로 구성되어 있으며, 각 백업 폴더에는**같은 구조**그 파일`.agents/`활성 : INDEX, SESSIONS_HISTORY, COMPLETED_TASKS_ARCHIVE, sessions/. 이것은 만능 상자가 아닙니다. 이것은**타임스탬프가 찍힌 스냅샷**. 그렇다고 해도 이것이 간소화된 버전 관리 메커니즘이라고 말할 수 있다 — 다만 개별 파일을 버전 관리하는 것이 아니라 특정 시점 T에서의 거버넌스 전체 패키지를 버전 관리한다는 차이점이 있다. 과거 정보를 찾아야 할 때, 중앙 인덱스가 필요하지 않습니다. 두 가지 옵션이 있습니다 : 1. **grep` 목표된**:`grep -r "zsh" backup/Y2026-001-039/`— 그리고 zsh를 언급하는 모든 것을 기간 동안 찾으세요, 어떤 관점이든 (INDEX, SESSIONS_HISTORY, 세션 아카이브). 2. **수동 재통합**: 당신은 백업 폴더를 활성 컨텍스트에 일시적으로 복사하고, 해당 특정 기간을 분석하도록 에이전트에게 요청합니다. 인덱스는 암시적이다. 그것은 파일의 구조 자체에 있다 — 각각은 이미 그 자체의 관점에서 인덱스이다. == 선반의 은유 기구를 직관적으로 만들기 위해, 저는 그것을 세 개의 선반으로 개념화했습니다 : * **선반 1 (EAGER)**— 작업 계획. 내가 지금 필요한 것 *지금*. INDEX 최근, PROMPT_REPRISE, absolue적인 규칙. 가벼운, 즉각적인, 중요한. * **선반 2 (LAZY)**— 상담용 도서관. 요청 시 내가 가져올 수 있는 것. 기술 참조, 최근 기록, 절차. 더 크지만 메모리에 로드되지 않음. * **동굴 (backup/)**— 차가운 아카이브. 지난 것들이지만 버리기를 원하지 않는 모든 것. 에이전트는 그곳에 들어가지 않는다. 인간은 증류하고 싶을 때 그곳으로 내려간다. 에이전트는 처음에 네 번째 선반 — 하나`index-backup.adoc`그것은 LAZY이면서 전체 백업의 목차를 포함할 것이었습니다. 나는 거절했습니다. 그것은 이미 선형 성장에 시달리는 시스템에 또 하나의 중복이 될 것입니다. 아카이브된 파일의 구조는 이미 인덱스입니다. == 두 트리거 센서 개념화는 탄탄했지만 여전히 사각지대가 있었다:**정확히 언제 회전을 트리거해야 하나요?**기본 문서는 이를 개방된 질문으로 식별했습니다. 2일 후, 답변은 6개 프로젝트의 거버넌스 파일에 코드화되었습니다: 두 트리거를 가진 센서. === 자동 트리거 — `N % 10 == 0 첫 번째 트리거는 수학적입니다. 세션 번호가 10의 배수일 때 — 세션 10, 20, 30, 40 — 백업 로테이션이 세션 종료 절차 내에서 자동으로 실행되며, 이는 단계 6 직후입니다. 왜 10일까? 두 상반된 힘 사이의 타협점이다: 너무 짧은 윈도우(5세션)는 연속성에 필요한 맥락을 잃고; 너무 긴 윈도우(20세션)는 맥락 비대 문제를 해결하지 못한다. 하루에 한두 세션 정도를 유지하면 10세션은 약 일주일分の 작업 시간을 커버한다 — 에이전트가 최근 결정을 기억하기에는 충분하지만, 맥락이 폭주하기에는 부족하다. === 임계치 트리거 — 500 라인 EAGER 두 번째 트리거는 동적입니다. 세션 번호에 관계없이 누적된 EAGER 파일이 초과하면**500 줄**, 회전이 시작됩니다. 이 임계값은 세션이 예외적으로 생산적인 시나리오 — 즉, 짧은 세션에 많은 콘텐츠가 작성됨 — 에 대비합니다. 120줄의 편집 콘텐츠를 생성하는 세션은 COMPLETED_TASKS_ARCHIVE를 두 줄을 수정하는 디버그 세션보다 훨씬 빠르게 증가시킵니다. 500줄의 임계값은 측정된 via`wc -l .agents/INDEX.adoc .agents/archives/COMPLETED_TASKS_ARCHIVE_*.adoc PROMPT_REPRISE.adoc`, 이 비대칭을 포착한다. === 수동 트리거 — "회전 백업 마침내, 인간이 주도권을 유지한다. 키워드`rotation backup`, `backup rotation` ou `lance la rotation backup`요청에 따라 세션 종료와 무관하게 절차가 시작됩니다. 컨텍스트가 무거워지는 것을 느끼지만 아직 10의 배수가 아닌 경우이거나, 새로운 작업을 시작하기 전에 현재 작업 단계를 보관하고 싶을 때 유용합니다. [plantuml, format=svg, id=diag-capteur-trigger, alt="Les trois déclencheurs du capteur de rotation backup — automatique, seuil, manuel"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 200 title 백업 회전 센서 — 세 가지 트리거 start :Procédure de fin de session; note right: Mots-clés "세션 종료"\nou "여기서 멈추자" :Étapes 1 à 6\n(archivage standard); note right 1. Archive sessions/N.adoc 2. MAJ PROMPT_REPRISE 3. MAJ SESSIONS_HISTORY 4. MAJ INDEX.adoc 5. MAJ TEST_COVERAGE 6. MAJ COMPLETED_TASKS end note if (N % 10 == 0\nOU\nEAGER cumulé > 500 lignes ?) then (oui) :⚙️ Rotation Backup\n(étape 7); note right 1. Créer backup/Y20XX-sessions-X-Y/ 2. Copier intégrale INDEX + HISTORY + COMPLETED_TASKS + sessions/ 3. Tronquer actifs à 10 sessions 4. Ajouter _Localisation active_ end note else (non) :Pas de rotation; endif :Checklist [✅] x 7\n(si applicable); stop @enduml ---- 이 다이어그램은 세션 종료 절차에서 센서의 정확한 삽입을 보여줍니다. 7단계는 선택적입니다 — 두 조건 중 하나가 참일 때만 실행되지만 — 그러나 항상 *검증*됩니다. 최종 체크리스트에는`[✅] 7. Backup roté (si applicable)`. === 폐쇄된 루프 이 센서는 이전 기사에서 열린 루프를 닫습니다. Eager/Lazy 거버넌스는 두 세션 간의 에이전트 메모리 문제를 해결했습니다. Hot/Warm/Cold 메커니즘은 증가하는 메모리 문제를 해결했습니다. 두 트리거가 있는 센서는 *quand* 문제를 해결하여 — 인간이 컨텍스트 크기를 모니터링하는 정신적 부담을 덜어줍니다. [plantuml, format=svg, id=diag-boucle-fermee, alt="Les trois couches de la gouvernance agent — Eager/Lazy, Hot/Warm/Cold, Capteur"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title 에이전트 거버넌스의 세 계층 left to right direction package "층 1 — 메모리 (조항 0108)" as C1 #E8F5E9 { rectangle "**EAGER** 대시보드 자동 충전" as EAG rectangle "**LAZY**\n소유자 매뉴얼\n요청 시 로드" as LAZ EAG -[hidden]right-> LAZ } package "층 2 — 노화 (제0110조)" as C2 #FFF9C4 { rectangle "HOT 10개의 활성 세션 ~300줄" as HOT rectangle "**WARM** 참조 절차" as WRM rectangle "**COLD** backup/ 차가운 파도" as CLD HOT -[hidden]right-> WRM WRM -[hidden]right-> CLD } package "3층 — 트리거 (오늘)" as C3 #BBDEFB { rectangle "**자동** N % 10 == 0" as AUTO rectangle "**임계값** > 500 라인" as SEUIL rectangle "**Manuel** 회전 백업" as MAN AUTO -[hidden]right-> SEUIL SEUIL -[hidden]right-> MAN } C1 --> C2 : "메모리 크기가 증가한다\n→ 메커니즘이 필요합니다\n노화" C2 --> C3 : "노화 → 트리거가 필요합니다 실행하기 위해" note bottom of C3 ✅ Déployé sur 6 projets magic-stick · bakery-gradle plantuml-gradle · cheroliv.com jhipster-gradle-plugins quizz-benchmark-gradle end note @enduml ---- 세 층이 논리적으로 쌓입니다. 첫 번째 층은 에이전트에게 기억을 제공합니다. 두 번째 층은 이 기억이 에이전트를 압도하는 것을 방지합니다. 세 번째 층은 이 기억의 유지 관리를 자동화하여 인간이 그에 대해 생각하지 않아도 되도록 합니다. === cheroliv.com에서의 효과적인 마이그레이션 메커니즘은 이론적으로 남아 있지 않았습니다. 위에서`cheroliv.com`, 첫 번째 백업 로테이션은 2026년 4월 29일에 실행되었습니다 — 세션 -6부터 2까지가 이동했습니다.`.agents/backup/Y2026-sessions-neg6-a-002/` : |=== |파일 |회전 전 |회전 후 |이득 |`.agents/INDEX.adoc` |19개 세션 나열 |10회 (3-12) |-9 항목 |`.agents/SESSIONS_HISTORY.adoc` |18 세션 |10 세션 |-8개 항목 |`COMPLETED_TASKS_ARCHIVE` |161줄 (세션 1-12) |135 라인 (세션 3-12) |-26 줄 |`sessions/` |20개의 파일 |10 파일 |-10 파일 |**백업/** |존재하지 않는 |1차 한파 (보관된 10개 세션) |+1 냉동 팩 |=== 라인 수의 증가량은 작았습니다 — 프로젝트는 아직 어리고, 12세션이었습니다 — 중요한 것은 그것이**메커니즘이 마련되어 있습니다.**. 다음 자동 회전은 세션 20에서 트리거되거나, 500개의 EAGER 라인에 도달하면 더 일찍 트리거됩니다. == 인간-에이전트 수업 이 세션 048은 IA 에이전트와의 협업에서 근본적인 것을 배웠습니다. 에이전트는 자연스러운 편향이 있다: 그것은 시도한다**최적화하다**, à **간소화하다**, à **중복을 제거하다**. 이것은 깨끗하고 간결한 응답을 생성하도록 훈련된 시스템의 편향이다. 데이터셋이 풍부하고 다차원적이면, 그의 첫 번째 반응은 그것을 가장 간단한 형태로 줄이는 것이다. 인간은 그와 달리 다른 직관을 가지고 있다: 그는 구조적 중복이 무언가임을 직감한다**장점**, 그것이 결함이 아닙니다. 같은 현실에서의 다양한 관점이 바로 나중에 품질 높은 증류를 가능하게 할 것입니다. 에이전트가 틀린 것이 아니다. 그의 "optimum"은 내 것이 아니다. 에이전트는 를 위해 최적화한다**현재**— 즉각적인 맥락, 제기된 질문에 대한 빠른 답변. 인간은 이를 위해 최적화한다**미래**— 3개월 혹은 3년 이내에 찾아내고, 교차시키고, 증류하는 능력 ____ 내가 원하는 것은 원본 자료야. 너의 생각, 주저함, 그리고 나의 질문에 대한 답변. 네 요약은 아니야. 요약은 내가 너보다 더 잘 만들 수 있어. 내가 원하는 것은 원본 자료야. ____ 세션 끝에 내가 그에게 한 이 말이 모든 것을 요약한다. 에이전트는 생산 도구다. 인간은 증류 도구다. 거버넌스는 에이전트가 모든 것을 스스로 이해하도록 하기 위한 것이 아니라 — 인간이 나중에 생산된 물질을 다룰 수 있도록 하기 위한 것이다. 같은 차가운 파도는 이 철학의 건축적 번역이다: 아무것도 버리지 않고, 아무것도 합치지 않고, 아무것도 재인덱스하지 않는다. 패키지를 그대로 이동한다. 증류는 나중에 수작업으로 인간이 수행한다. == 이전 글의 논리적 연속 읽으셨다면link:/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[Eager/Lazy 전략에 관한 기사], 당신은 자연스러운 진행을 인식하게 될 것입니다 : 1. **제108조**— Eager/Lazy 거버넌스 : *comment* 에이전트 컨텍스트를 두 가지 가용성 수준으로 구성하는 방법 2. **이 글 0110**— 백업 메커니즘 : *어떻게* 이 컨텍스트를 잃지 않고 오래 보존할 수 있을까, 너무 커질 때 첫 번째 기사는 다음과 같은 질문에 답했습니다: « 에이전트는 두 세션 사이에서 아무것도 기억하지 못합니다. 어떻게 그에게 기억을 줄 수 있을까요? 이것은 첫 번째에서 불가피하게 이어지는 질문에 답한다: « 메모리는 각 세션마다 증가하는데, 이를 지우지 않고 에이전트를 질식시키는 것을 어떻게 막을 수 있을까? 답은 하나의 패턴으로 요약됩니다:**더운/따뜻한/추운**, 거버넌스 파일에 적용된. 그리고 하나의 원칙 :**절대 아무것도 잃지 말고, 항상 모든 것을 재배치하라**. == 링크 * 이전 글 :link:/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[AsciiDoc를 사용해 AI 에이전트 관리하기] * 내 사이트 : https://cheroliv.com * 프로젝트`magic-stick`: https://github.com/cheroliv/magic-stick --- *좋은 거버넌스 시스템은 결코 데이터를 삭제하지 않습니다. 그것을 보관합니다.* ----</code></pre> </div> </div> </div> </div> https://cheroliv.com/blog/2026/0109_gradle_jhipster_docker_testcontainers_debugging_post.html Sat, 25 Apr 2026 00:00:00 +0000 blog/2026/0109_gradle_jhipster_docker_testcontainers_debugging_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_현장_jhipster_프로젝트_더_이상_로드되지_않는_빌드">현장 : JHipster 프로젝트, 더 이상 로드되지 않는 빌드</a></li> <li><a href="#_오류_1_유령_변수_reportsdir">오류 1 : 유령 변수 `reportsDir</a></li> <li><a href="#_오류_2_main_더_이상_gradle_9에서_존재하지_않습니다">오류 2 : <code>main = "…​"</code> 더 이상 Gradle 9에서 존재하지 않습니다.</a></li> <li><a href="#_오류_3_sourcecompatibility는_더_이상_프로젝트_속성이_아닙니다">오류 3: `sourceCompatibility`는 더 이상 프로젝트 속성이 아닙니다.</a></li> <li><a href="#_오류_4_세_피연산자_groovy_어서션">오류 4: 세 피연산자 Groovy 어서션</a></li> <li><a href="#_오류_5_암묵적_의존성_compilekotlin_openapigenerate">오류 5 : 암묵적 의존성 <code>compileKotlin</code> → `openApiGenerate</a></li> <li><a href="#_오류_6_generategitproperties가_filteroutputstream_write에서_실패합니다">오류 6 : `generateGitProperties`가 `FilterOutputStream.write()`에서 실패합니다.</a></li> <li><a href="#_마지막으로_testcontainers가_무대에_등장합니다">마지막으로: Testcontainers가 무대에 등장합니다.</a></li> <li><a href="#_phase_1_docker_java_트랙">Phase 1 : docker-java 트랙</a></li> <li><a href="#_2단계_웹_검색_및_github_브레드크럼">2단계 : 웹 검색 및 GitHub 브레드크럼</a></li> <li><a href="#_3단계_이름이_바뀐_아티팩트의_함정">3단계 : 이름이 바뀐 아티팩트의 함정</a></li> <li><a href="#_4단계_해결_강제">4단계 : 해결 강제</a></li> <li><a href="#_최종_결과">최종 결과</a></li> <li><a href="#_수정_사항_요약표">수정 사항 요약표</a></li> <li><a href="#_결론">결론</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽기 시간 : 15 minutes</div> <p>당신은 이미 그 순간을 경험했습니다. 단순한`./gradlew build`당신이 하루에 100번 실행하는 것이 갑자기 한 번도 본 적 없는 오류로 인해 멈추기 시작한다면? 이를 연속 11번의 오류로 곱하고, Docker Engine 29 호환성 문제를 충분히 추가한 뒤, 10년 동안 사용해 온 API를 삭제하는 Gradle 9을 뿌리세요. 여기서 전체 로그를 확인할 수 있습니다.</p> </div> <hr> <div class="paragraph"> <div class="title">다이어그램 1 — Gradle 9 마이그레이션 (오류 체인)</div> <p>목적 : 불호환 시리즈를 보여주다</p> </div> <div class="listingblock"> <div class="title">👉 명료하고 Gradle에 중점을 둔</div> <div class="content"> <pre>@startuml left to right direction title Gradle 9 마이그레이션 rectangle "1 reportsDir" as A rectangle "2 mainClass" as B rectangle "3\nsourceCompatibility" as C rectangle "4 Groovy assert" as D A --> B B --> C C --> D @enduml</pre> </div> </div> <hr> <div class="paragraph"> <div class="title">다이어그램 2 — 호환되지 않는 JHipster 플러그인</div> <p>목표 : 손상된 플러그인 격리</p> </div> <div class="listingblock"> <div class="title">👉 의존성에 대한 명확한 비전.</div> <div class="content"> <pre>@startuml left to right direction title 수정해야 할 플러그인 skinparam shadowing false skinparam roundcorner 18 rectangle "1 openApiGenerate" as A #FFF3E0 rectangle "2 gitProperties 2.5.7" as B #FFF3E0 rectangle "3 버전 수정된" as C #E3F2FD rectangle "4 조립 OK" as D #E8F5E9 A --> B B --> C C --> D @enduml</pre> </div> </div> <hr> <div class="paragraph"> <div class="title">도표 3 — Docker 29 / Testcontainers</div> <p>목표: 런타임 문제</p> </div> <div class="listingblock"> <div class="title">👉 명확한 런타임 기록.</div> <div class="content"> <pre>@startuml left to right direction title Docker 29 와 Testcontainers skinparam shadowing false skinparam roundcorner 18 skinparam defaultFontSize 14 rectangle "1 조립 OK" as A #E8F5E9 rectangle "2\n테스트 Cucumber 실패" as B #FFEBEE rectangle "3 Testcontainers 1.32 거부" as C #FFF3E0 rectangle "4 업그레이드 버전" as D #E3F2FD rectangle "5\n빌드 최종 OK" as E #E8F5E9 A --> B B --> C C --> D D --> E @enduml</pre> </div> </div> <hr> <div class="listingblock"> <div class="title">그것을 표현하는 또 다른 방법</div> <div class="content"> <pre>@startuml !option handwritten true skinparam backgroundColor #FEFEFE skinparam shadowing false skinparam defaultFontName Inter skinparam defaultFontSize 14 skinparam ArrowThickness 2 skinparam RoundCorner 18 title 안정화 로드맵 — Gradle 9부터 최종 빌드까지 left to right direction rectangle "⚙️ Gradle 9 마이그레이션" as A #E3F2FD rectangle "🧩 JHipster 플러그인" as B #FFF3E0 rectangle "🐳 Docker 29\nTestcontainers" as C #FCE4EC rectangle "✅ 안정적인 빌드" as D #E8F5E9 note bottom of A reportsDir mainClass sourceCompatibility Groovy assert end note note bottom of B openApiGenerate gitProperties versions alignées end note note bottom of C tests Cucumber KO image Docker rejetée upgrade libs end note A -[#42A5F5]-> B : corrections build.gradle B -[#FB8C00]-> C : assemble OK C -[#E53935]-> D : tests réparés @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_현장_jhipster_프로젝트_더_이상_로드되지_않는_빌드">현장 : JHipster 프로젝트, 더 이상 로드되지 않는 빌드</h2> <div class="sectionbody"> <div class="paragraph"> <p>프로젝트`edster`는 2024년에 생성된 JHipster 애플리케이션입니다. 루트 빌드 스크립트`build.gradle`개월 동안 안정 상태를 유지했습니다. 그러고 나서 버전 업그레이드를 결정했습니다 :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1436%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">컴포넌트</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">대상 버전</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">9.4.1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">자바</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">21.0.11-tem (Eclipse Temurin)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">JHipster</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8.x (프레임워크`tech.jhipster:jhipster-framework:8.11.0`)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">스프링 부트</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3.4.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">코틀린</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2.3.0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">도커 엔진</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">29.4.1 (API 1.54)</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>자바 버전 변경은 SDKMAN을 통해 이루어집니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sdk use java 21.0.11-tem</code></pre> </div> </div> <div class="paragraph"> <p>첫 번째 발사:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew build --no-daemon FAILURE: Build failed with an exception. * Where: Build file '/home/.../edster/build.gradle' line: 18 * What went wrong: An exception occurred applying plugin request [id: 'jhipster.cucumber-conventions'] > Failed to apply plugin 'jhipster.cucumber-conventions'. > Could not create task ':cucumberTest'. > Could not create task ':consoleLauncherTest'. > Could not set unknown property 'reportsDir' for task ':consoleLauncherTest'</code></pre> </div> </div> <div class="paragraph"> <p>우리는 빌드 스크립트 로딩조차 벗어나지 못한다. 문제는`buildSrc/src/main/groovy/jhipster.cucumber-conventions.gradle`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_오류_1_유령_변수_reportsdir">오류 1 : 유령 변수 `reportsDir</h2> <div class="sectionbody"> <div class="paragraph"> <p>스크립트`jhipster.cucumber-conventions.gradle`포함:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">tasks.register('consoleLauncherTest', JavaExec) { dependsOn(testClasses) String cucumberReportsDir = file("$buildDir/reports/tests") outputs.dir(reportsDir) // <-- reportsDir n'existe PAS classpath = sourceSets["test"].runtimeClasspath main = "org.junit.platform.console.ConsoleLauncher" // ... }</code></pre> </div> </div> <div class="paragraph"> <p>정의된 변수는`cucumberReportsDir`. 사용된 것은`reportsDir`-- 어디에서도 정의되지 않은.</p> </div> <div class="paragraph"> <p><strong>수정</strong>:`outputs.dir(cucumberReportsDir)`</p> </div> </div> </div> <div class="sect1"> <h2 id="_오류_2_main_더_이상_gradle_9에서_존재하지_않습니다">오류 2 : <code>main = "…​"</code> 더 이상 Gradle 9에서 존재하지 않습니다.</h2> <div class="sectionbody"> <div class="paragraph"> <p>즉시 재시작 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">Could not set unknown property 'main' for task ':consoleLauncherTest' of type org.gradle.api.tasks.JavaExec.</code></pre> </div> </div> <div class="paragraph"> <p>Gradle 9는 속성을 제거합니다`main`의 이익을 위해`mainClass`과제에`JavaExec`.</p> </div> <div class="paragraph"> <p><strong>수정</strong> : <code>mainClass = "org.junit.platform.console.ConsoleLauncher"</code></p> </div> </div> </div> <div class="sect1"> <h2 id="_오류_3_sourcecompatibility는_더_이상_프로젝트_속성이_아닙니다">오류 3: `sourceCompatibility`는 더 이상 프로젝트 속성이 아닙니다.</h2> <div class="sectionbody"> <div class="paragraph"> <p>새 오류:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">Could not set unknown property 'sourceCompatibility' for root project 'edster' of type org.gradle.api.Project.</code></pre> </div> </div> <div class="paragraph"> <p>루트 스크립트는 다음과 같았습니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">sourceCompatibility=17 targetCompatibility=17</code></pre> </div> </div> <div class="paragraph"> <p>Gradle 9은 루트 수준에서 이러한 속성을 제거합니다. 이러한 속성은 블록 내에서 존재해야 합니다.<code>java</code>.</p> </div> <div class="paragraph"> <p><strong>수정</strong>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">java { sourceCompatibility = JavaVersion.VERSION_21 targetCompatibility = JavaVersion.VERSION_21 }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_오류_4_세_피연산자_groovy_어서션">오류 4: 세 피연산자 Groovy 어서션</h2> <div class="sectionbody"> <div class="paragraph"> <p>이전 스크립트에는:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">assert System.properties["java.specification.version"] == "17" || "21" || "24"</code></pre> </div> </div> <div class="paragraph"> <p>Groovy에서는,<code>"21"</code> et <code>"24"`진실한 문자열이다. 표현은 …​로 해결됩니다</code>(…​ == "17") || true || true`, 항상 참인 것 — 하지만 원하는 엄격한 주장에 대한 구문은 유효하지 않습니다.</p> </div> <div class="paragraph"> <p><strong>수정</strong>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">assert System.properties["java.specification.version"] in ["17", "21", "23", "24"]</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_오류_5_암묵적_의존성_compilekotlin_openapigenerate">오류 5 : 암묵적 의존성 <code>compileKotlin</code> → `openApiGenerate</h2> <div class="sectionbody"> <div class="paragraph"> <p>빌드가 진행 중입니다. Kotlin 컴파일이 성공했습니다. 그리고 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">Task ':compileKotlin' uses this output of task ':openApiGenerate' without declaring an explicit or implicit dependency.</code></pre> </div> </div> <div class="paragraph"> <p>Gradle 9은 태스크 사이의 암시적 의존성을 거부합니다. 왜냐하면`compileKotlin`생성된 소스를 읽는`openApiGenerate`, 링크를 선언해야 합니다.</p> </div> <div class="paragraph"> <p><strong>수정</strong>안에`build.gradle`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">afterEvaluate { tasks.named("compileKotlin").configure { dependsOn(tasks.named("openApiGenerate")) } }</code></pre> </div> </div> <div class="paragraph"> <p>Le `afterEvaluate`필요합니다 왜냐하면`openApiGenerate`OpenAPI Generator 플러그인(확장 기능)이며, 구성 단계에서 직접 접근할 수 있는 작업이 아닙니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_오류_6_generategitproperties가_filteroutputstream_write에서_실패합니다">오류 6 : `generateGitProperties`가 `FilterOutputStream.write()`에서 실패합니다.</h2> <div class="sectionbody"> <div class="paragraph"> <p>Java 컴파일이 성공합니다. 리소스가 처리됩니다. 그 후에 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">> Task :generateGitProperties FAILED No signature of method: java.io.FilterOutputStream.write() is applicable for argument types: (Integer) values: [103]</code></pre> </div> </div> <div class="paragraph"> <p>플러그인`gradle-git-properties`version 2.5.0는 Java 21 / Gradle 9와 호환되지 않습니다. 내부 버그가 호출을 시도합니다`write(int)`그루비를 통해 스트림이 닫힌 것.</p> </div> <div class="paragraph"> <p><strong>수정</strong>안에`gradle.properties` :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties">gitPropertiesPluginVersion=2.5.7</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_마지막으로_testcontainers가_무대에_등장합니다">마지막으로: Testcontainers가 무대에 등장합니다.</h2> <div class="sectionbody"> <div class="paragraph"> <p>여기까지는 순수한 "build script debugging"이었다. 각 오류는 빌드 스크립트에서의 Gradle 9 또는 Java 21 호환성 문제였다. 위에서 언급한 여섯 가지 수정을 마친 후,`./gradlew assemble`성공적으로 통과합니다.</p> </div> <div class="paragraph"> <p>하지만`./gradlew build`테스트도 실행하고, Cucumber 테스트는 Testcontainers를 사용하여 임시 PostgreSQL을 시작합니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">Could not find a valid Docker environment. EnvironmentAndSystemPropertyClientProviderStrategy: failed with exception BadRequestException (Status 400: {"message":"client version 1.32 is too old. Minimum supported API version is 1.40"} UnixSocketClientProviderStrategy: failed with exception BadRequestException (Status 400: {"message":"client version 1.32 is too old. Minimum supported API version is 1.40"}</code></pre> </div> </div> <div class="paragraph"> <p>Testcontainers은 Docker와 통신할 수 없습니다. 서로 다른 두 가지 전략(환경 변수 + Unix 소켓)이 동일한 오류에서 실패합니다.</p> </div> <div id="diag-docker-handshake" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam handwritten false actor "Testcontainers\n1.20.6" as TC participant "docker-java\n3.4.1" as DJ participant "도커 엔진 29.4.1" as DE TC -> DJ : new DockerClient() DJ -> DE : GET /_ping\nUser-Agent: docker-java/3.4.1\nAPI-Version: 1.32 DE --> DJ : HTTP 400 Bad Request\nclient version 1.32 is too old.\nMinimum supported API version is 1.40 DJ --> TC : BadRequestException TC --> TC : Could not find a valid\nDocker environment note right of DE Docker Engine 29.x impose API minimum = 1.40 (défaut ancien : 1.24) end note note left of DJ docker-java 3.4.1 envoie hardcoded API version 1.32 dans l'en-tête HTTP end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_phase_1_docker_java_트랙">Phase 1 : docker-java 트랙</h2> <div class="sectionbody"> <div class="paragraph"> <p>첫 번째 반응: Testcontainers에서 사용하는 Java Docker 클라이언트가 API 버전을 전송`1.32`그의 HTTP 핸드셰이크에서, 하지만 Docker Engine 29.4.1은 최소한을 요구한다`1.40`. 문제는 클라이언트 측에 있으며, 데몬 측이 아닙니다.</p> </div> <div class="paragraph"> <p>Testcontainers 1.20.6에 의해 해결된 docker-java 버전 검증 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew dependencies --configuration testRuntimeClasspath | grep docker-java +--- com.github.docker-java:docker-java-api:3.4.1 +--- com.github.docker-java:docker-java-transport:3.4.1</code></pre> </div> </div> <div class="paragraph"> <p>docker-java 3.4.1, Testcontainers 1.20.6에서 유래한 버전입니다. docker-java의 최신 공개 버전은 3.5.1입니다. 우리는 버전 강제 업그레이드를 시도해 봅니다.<code>resolutionStrategy`블록 안에`configurations</code> de <code>build.gradle</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">configurations { all { resolutionStrategy.eachDependency { details -> if (details.requested.group == "com.github.docker-java" && details.requested.name.startsWith("docker-java")) { details.useVersion("3.5.1") } } } }</code></pre> </div> </div> <div class="paragraph"> <p>빌드를 다시 시작합니다. 같은 오류:`client version 1.32 is too old`.</p> </div> <div class="paragraph"> <p>Gradle 캐시 확인: JAR이 다시 다운로드되었지만 오류가 계속됩니다. docker-java 3.5.1은 여전히 보냅니다`1.32`. 이 버전은 따라서 Docker Engine 29.4.1에 충분하지 않습니다.</p> </div> <div class="paragraph"> <p><strong>정화 작용</strong>: Gradle 캐시를 완전히 비우기, 확실히 하기 위해 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">rm -rf ~/.gradle/caches rm -rf /path/to/project/.gradle</code></pre> </div> </div> <div class="paragraph"> <p>정리 후 전체 재시작. 같은 오류.</p> </div> </div> </div> <div class="sect1"> <h2 id="_2단계_웹_검색_및_github_브레드크럼">2단계 : 웹 검색 및 GitHub 브레드크럼</h2> <div class="sectionbody"> <div class="paragraph"> <p>docker-java 3.5.1은 부족합니다. 이제 누군가가 이 정확한 문제를 겪었는지 찾아볼 수밖에 없습니다.</p> </div> <div class="paragraph"> <p>testcontainers-java 및 docker-java 이슈에 대한 집중된 검색:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">site:github.com/testcontainers "client version 1.32 is too old" site:github.com/docker-java "client version 1.32" Docker Engine 29</code></pre> </div> </div> <div class="paragraph"> <p>즉시 결과:</p> </div> <div class="ulist"> <ul> <li> <p><a href="https://github.com/testcontainers/testcontainers-java/issues/11210">testcontainers-java#11210</a>—<code>[Bug]: client version 1.32 is too old. Minimum supported API version is 1.44</code></p> </li> <li> <p><a href="https://github.com/testcontainers/testcontainers-java/issues/11212">testcontainers-java#11212</a>—<code>[Bug]: Docker 29.0.0 could not find a valid Docker environment</code></p> </li> <li> <p><a href="https://github.com/testcontainers/testcontainers-java/issues/11491">testcontainers-java#11491</a>—<code>[Bug]: Incompatibility in Ubuntu Github runners with Docker Engine 29.1.*</code></p> </li> </ul> </div> <div class="paragraph"> <p>아리아드네의 실은 명확합니다: Docker Engine 29.x는 최소 API 버전을 올렸다`1.24`(이전 결함) 에`1.40`. Testcontainers 1.20.x는 docker-java 3.4.x를 사용하여 API 버전을 협상하여 보내는`1.32`. 데몬은 예의 바르게 그러나 단호히 거부합니다.</p> </div> <div class="paragraph"> <p>이슈 #11491에서, 유지관리자가 답변합니다 :</p> </div> <div class="paragraph"> <p><em><em>_ 안녕하세요, 저는 GH 러너에서 엔진 29.1을 사용하는 버전 2.0.3으로 실행되는 프로젝트가 있는데, 잘 작동합니다. 모두 버전 충돌이 없는지 확인해 주실 수 있나요? 모든 모듈이 무언가로 prefix되었음을 기억해 주세요`testcontainers-<code>. 그래서 버전 2.x부터 우리는 …​부터 시작했습니다`postgresql</code> to <code>testcontainers-postgresql</code> </em>_</em></p> </div> <div class="paragraph"> <p>이 답변에는<strong>두 개의 중요한 정보</strong>:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Testcontainers 2.0.3+은 문제를 해결합니다</p> </li> <li> <p>모듈들이<strong>testcontainers-` 접두사로 이름이 바뀐</strong></p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_3단계_이름이_바뀐_아티팩트의_함정">3단계 : 이름이 바뀐 아티팩트의 함정</h2> <div class="sectionbody"> <div class="paragraph"> <p>이름 변경은 가혹합니다. Testcontainers 2.x에서는 더 이상 과거 이름 중 어느 것도 해당 이름으로 작동하지 않습니다:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">이전 이름 (1.x)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">새 이름 (2.x)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:postgresql</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:testcontainers-postgresql</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:jdbc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:testcontainers-jdbc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:junit-jupiter</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:testcontainers-junit-jupiter</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:testcontainers</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">변경되지 않은</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>첫 번째 시도: Testcontainers BOM 2.0.5를 적용하고 새로운 아티팩트 이름을 안에`build.gradle`.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">dependencies { testImplementation platform("org.testcontainers:testcontainers-bom:2.0.5") testImplementation "org.testcontainers:testcontainers-postgresql" testImplementation "org.testcontainers:testcontainers-jdbc" testImplementation "org.testcontainers:testcontainers-junit-jupiter" testImplementation "org.testcontainers:testcontainers" }</code></pre> </div> </div> <div class="paragraph"> <p><code>./gradlew build</code></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">FAILURE: Could not find org.testcontainers:jdbc:2.0.5. Could not find org.testcontainers:junit-jupiter:2.0.5.</code></pre> </div> </div> <div class="paragraph"> <p><strong>testcontainers-bom의 BOM은 충분하지 않다.</strong>왜? Spring Boot 3.4.5가 자체적인 의존성 관리 BOM을 노출하기 때문에 (<code>spring-boot-dependencies</code>) 누구<strong>이긴다</strong>Testcontainers BOM의 전달적 해결에서 Spring Boot이 고정합니다`testcontainers` à <code>1.20.6</code>, 따라서 Spring Boot BOM에 명시적으로 들어 있지 않은 모든 아티팩트(예: 새로운`testcontainers-*<code>) 이전 이름으로 해결됩니다`1.20.6</code>-- 더 이상 존재하지 않는 이 버전.</p> </div> <div class="paragraph"> <p>점검하면서`dependencies --configuration testRuntimeClasspath`, 찾을 수 있습니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">+--- org.testcontainers:testcontainers -> 1.20.6 (*) | \--- org.testcontainers:testcontainers:2.0.5 -> 1.20.6</code></pre> </div> </div> <div class="paragraph"> <p>Le <code>→`나타나냅니다 대체 : Testcontainers 2.0.5가 *요구*됩니다, 하지만 Spring Boot이 강제합니다`1.20.6</code>.</p> </div> <div id="diag-bom-war" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam handwritten false skinparam componentStyle rectangle left to right direction component "build.gradle (소비자)" as BG #E3F2FD { rectangle "요청 `testcontainers-bom:2.0.5" as REQ rectangle "요청 `testcontainers-postgresql" as REQ2 } component "Maven 중앙" as MC #FFF3E0 component "선언" as DEC #E8F5E9 { rectangle "testcontainers-bom:2.0.5` 수정 2.0.5" as BOM2 rectangle "spring-boot-dependencies:3.4.5`\n고정 1.20.6" as BOM1 } component "Gradle 해결" as RES #FFEBEE { rectangle "우승 버전 `testcontainers:1.20.6" as WIN #EF9A9A } BG --> DEC : "BOM을 분석하다" BOM2 --> RES : "제안 2.0.5" BOM1 --> RES : "제안하다 1.20.6" WIN -> MC : "다운로드 testcontainers:1.20.6" note bottom of WIN Spring Boot BOM prime car le plugin spring-boot applique ses dépendances de gestion après la résolution du consommateur end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_4단계_해결_강제">4단계 : 해결 강제</h2> <div class="sectionbody"> <div class="paragraph"> <p>전략이 두 배가 됩니다 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>docker-java를 버전 3.7.1로 강제 지정 (Docker Engine 29와 호환됨으로 테스트됨)</p> </li> <li> <p>Spring Boot BOM을 우회하여 Testcontainers core를 2.0.5로 강제</p> </li> </ol> </div> <div id="diag-resolution-override" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam handwritten false skinparam componentStyle rectangle left to right direction component "build.gradle (resolutionStrategy와 함께)" as BG #E8F5E9 { rectangle "BOM Testcontainers `2.0.5" as BOM2 rectangle "resolutionStrategy\n.eachDependency" as RS #66BB6A } component "해결된 갈등" as RESOLVED #E3F2FD { rectangle "docker-java `3.7.1` (강제)" as DJ rectangle "testcontainers `2.0.5` (강제)" as TC #81C784 rectangle "testcontainers-postgresql `2.0.5" as TPG rectangle "testcontainers-jdbc `2.0.5" as TJ rectangle "testcontainers-junit-jupiter `2.0.5" as TJJ } component "BOM Spring Boot (암시적, 재정의된)" as BOM1 #FFEBEE component "Maven Central" as MC #FFF3E0 BG --> RESOLVED : "BOM Testcontainers 2.0.5\n바로 통과합니다" RS -> DJ : "힘 3.7.1" RS -> TC : "힘 2.0.5" RESOLVED --> MC : "JARs를 다운로드하세요\nDocker 29와 호환되는" BOM1 -[#gray,dashed]-> RESOLVED : "testcontainers에서 무시됨\ndocker-java" note bottom of RS Le `eachDependency` intercepte la résolution Gradle AVANT que le BOM Spring Boot ne gagne. C'est une intervention chirurgicale. end note @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>최종 수정</strong>안에`build.gradle`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">configurations { all { resolutionStrategy.eachDependency { details -> if (details.requested.group == "com.github.docker-java" && details.requested.name.startsWith("docker-java")) { details.useVersion("3.7.1") } if (details.requested.group == "org.testcontainers" && details.requested.name == "testcontainers") { details.useVersion("2.0.5") } } } } dependencies { testImplementation platform("org.testcontainers:testcontainers-bom:2.0.5") testImplementation "org.testcontainers:testcontainers-jdbc" testImplementation "org.testcontainers:testcontainers-junit-jupiter" testImplementation "org.testcontainers:testcontainers-postgresql" testImplementation "org.testcontainers:testcontainers" // ... autres dépendances Spring Boot }</code></pre> </div> </div> <div class="paragraph"> <p>Le `resolutionStrategy.eachDependency`이것이 BOM을 우회하는 유일한 방법이다`spring-boot-dependencies`Spring Boot 플러그인에 의해 관리됨. 동등 테스트`details.requested.name == "testcontainers"`은 의도적으로 제한적 : 핵심 모듈만 강제합니다. 모듈들`testcontainers-*`Testcontainers 2.0.5의 BOM을 명시적으로 선언했습니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_최종_결과">최종 결과</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew build --no-daemon > Task :consoleLauncherTest [2 containers found] [2 containers started] [2 containers successful] BUILD SUCCESSFUL in 1m 16s</code></pre> </div> </div> <div class="paragraph"> <p>Testcontainers 2.0.5 + docker-java 3.7.1은 드디어 Docker Engine 29.4.1을 통해 PostgreSQL 컨테이너를 생성할 수 있게 되었습니다. 최종 비즈니스 오류 (Cucumber 테스트에서의 HTTP 500)는 빌드 스크립트와 완전히 무관한 애플리케이션 문제입니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_수정_사항_요약표">수정 사항 요약표</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">#</th> <th class="tableblock halign-left valign-top">파일</th> <th class="tableblock halign-left valign-top">문제</th> <th class="tableblock halign-left valign-top">수정</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>buildSrc/src/main/groovy/jhipster.cucumber-conventions.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">변수`reportsDir`존재하지 않는</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>outputs.dir(cucumberReportsDir)</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>buildSrc/src/main/groovy/jhipster.cucumber-conventions.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`main`지원 종료된 Gradle 9</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>mainClass</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>build.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`sourceCompatibility`top-level 금지된 Gradle 9</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">블록`java { sourceCompatibility = JavaVersion.VERSION_21 }`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>build.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">구문적으로 잘못된 Groovy 어설션</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>assert …​ in ["17", "21", "23", "24"]</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>build.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">암시적 의존성`compileKotlin` → <code>openApiGenerate</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>afterEvaluate { tasks.named("compileKotlin").dependsOn("openApiGenerate") }</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">6</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>gradle.properties</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`gitPropertiesPluginVersion`호환되지 않는 Java 21</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>2.5.7</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">7</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Gradle 캐시</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">docker-java 3.5.1 테스트됨, 해결되었지만 부족함</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">정리 + 통과 docker-java 3.7.1</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">8</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>build.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Testcontainers 1.20.6는 Docker Engine 29와 호환되지 않습니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">강제 Testcontainers 2.0.5 + 접두사`testcontainers-*`+ resolutionStrategy 대 Spring Boot BOM</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_결론">결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>JHipster/Gradle 빌드가 Gradle 9 + Docker Engine 29로 버전 업그레이드 후 실패하면 오류는 두 가지 범주로 나뉩니다:</p> </div> <div class="paragraph"> <p><strong>빌드 스크립트 오류</strong>(첫 6개) : Gradle 9는 수년간 작동했던 속성과 구문을 제거합니다 (<code>sourceCompatibility=</code>, <code>main =</code>, <code>reportsDir</code>). 이것들은 새로운 API를 알면 이루어지는 기계적 마이그레이션입니다.</p> </div> <div class="paragraph"> <p><strong>Docker 런타임 오류</strong>(마지막 두) : Docker Engine 29.4.1은 API 클라이언트 버전 1.40 미만을 제외합니다. Testcontainers 1.20.6 (Spring Boot 3.4.5에 의해 강제됨)는 docker-java 3.4.1을 사용하며, 이는 버전 1.32를 전송합니다. Testcontainers 2.0.5와 docker-java 3.7.1만이 문제를 해결하며, 아티팩트 이름 변경 및 버전 강제를 통해`resolutionStrategy.eachDependency`Spring Boot의 내재된 BOM을 우회하는 유일한 방법.</p> </div> <div class="paragraph"> <p>프로젝트 루트의 Gradle 빌드 스크립트가 이제 깨끗합니다.`./gradlew build`Java 21, Gradle 9.4.1, Spring Boot 3.4.5 및 Docker Engine 29.4.1에서 실행됩니다.</p> </div> </div> </div> https://cheroliv.com/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html Fri, 24 Apr 2026 00:00:00 +0000 blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html <div class="sect1"> <h2 id="_요약">요약</h2> <div class="sectionbody"> <div class="paragraph"> <p>Opencode와 같은 IA 에이전트와 함께 여러 세션에 걸쳐 복잡한 프로젝트를 진행할 때 근본적인 문제에 직면하게 됩니다:<strong>컨텍스트 유출</strong>. 에이전트는 이전 세션을 기억하지 못합니다. 그에게 설명된 모든 것 — 아키텍처, 규약, 백로그 상태 — 가 손실되었습니다. 매 세션마다 이 컨텍스트를 재구성하는 것은 비용이 많이 들고 느리며 오류의 원인이 됩니다.</p> </div> <div class="paragraph"> <p>이 글은 이 문제를 해결하기 위해 내가 구축한 수공예 전략을 설명한다: AsciiDoc 파일을 기반으로 한 지속 가능한 거버넌스 시스템, 그리고 이분법<strong>즉시/지연</strong>컨텍스트 토큰 소비를 최적화하고, 그리고<strong>필수적인 세션 종료 절차</strong>연속성을 보장하기 위해</p> </div> </div> </div> <div class="sect1"> <h2 id="_장소_월요일_4월_21일_오전_9시">장소 : 월요일 4월 21일, 오전 9시</h2> <div class="sectionbody"> <div class="paragraph"> <p>Opencode를 다시 열어 Gradle 플러그인 작업을 이어갑니다.<code>plantuml-plugin</code>. 어제 저녁, 저는 API 키 풀의 아키텍트 담당자와 세 시간을 토론했습니다 — 라운드 로빈 로테이션, 할당량 관리, 자동 페일오버. 오늘 아침, 에이전트는 금붕어 눈으로 나를 바라본다.</p> </div> <div class="paragraph"> <p><em><em>_ — 안녕하세요, 저는 Opencode 어시스턴트입니다. 오늘 어떻게 도와드릴까요? </em>_</em></p> </div> <div class="paragraph"> <p>아니요 — 아 맞다, API 키 풀, 우리는 YAML 구조에 있었죠. 아니요 — 주의,<code>PlantumlManager`은 Kotlin 싱글톤 객체이지 클래스가 아닙니다. 아니요 — 아니, 어제 우리가 결정한 것이`SyntaxValidationResult`중첩된 sealed class 상태로 남아 있었다`PlantumlService</code>.</p> </div> <div class="paragraph"> <p>모든 것을 다시 해야 한다. 혹은 더 정확히 말하면, 모든 것을 다시 설명해야 한다. 나는 내 세션의 처음 20분을 들여 어제 에이전트가 이미 손에 넣었던 맥락을 재구성하는 데 쓸 것이다. 소모된 토큰으로 20분. 나는 코딩을 할 수도 있는 20분이지만, 대신 의무적인 교육을 하고 있다.</p> </div> <div class="paragraph"> <p>이것은 Opencode의 버그가 아닙니다. 이것은 대화형 LLM의 근본적인 성질입니다: 두 세션 사이에서는 작업 기억이<strong>완전히 삭제됨</strong>. 에이전트는 이전 미션, 내린 결정, 식별된 함정, 함께 작성한 코드를 기억하지 못한다</p> </div> <div class="paragraph"> <p>저는 그것을 수십 번 경험했습니다. 네 개의 동시에 진행되는 프로젝트에서요. 몇 주 동안 이어지는 세션과 함께요. 저는 계산해 보았습니다: 평균적으로,<strong>세션 시간의 30~40%</strong>에이전트를 재맥락화하는 데 전념되었다. 프로젝트 세션 87에서`plantuml-plugin`, 나는 무너졌다. 나는 더 이상 그 문제를 열 번째로 설명하는 것을 감당할 수 없어서`AttemptEntry`는 최상위 레벨의 data class인`DiagramProcessor.kt`.</p> </div> <div class="paragraph"> <p>내가 필요로 했던 건 시스템이었다. 해킹이 아니라. 진정한 거버넌스였다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_창세기_혼돈에서_방법으로">창세기 : 혼돈에서 방법으로</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_첫_번째_세션_어둠의_시대">첫 번째 세션 : 어둠의 시대</h3> <div class="paragraph"> <p>Opencode와 함께한 첫 번째 프로젝트,<code>plantuml-plugin</code>, 아무런 지배 구조 없이 시작되었습니다. 저는 질문을 하고, 에이전트가 답변하고, 우리는 반복하고, 세션이 끝납니다. 그리고 다음 날 우리는 다시 제로에서 시작합니다. 세션 1이었고, 그다음 세션 2, 그다음 세션 3…​ 결국 세션 62에 이르러서 저는 같은 아키텍처를 재설명하는 데 누적된 시간을 잃었다는 것을 깨달았습니다.</p> </div> <div class="paragraph"> <p>세션 62에서, 숫자들이 여기 있습니다:<strong>198개의 단위 테스트가 통과합니다</strong>, <strong>42개의 기능 테스트가 검증되었습니다</strong>, 플러그인이 작동합니다. 하지만 인지 비용은 감당할 수 없습니다. 각 새로운 세션은 프로젝트 구조에 대한 20분 독백으로 시작됩니다.</p> </div> </div> <div class="sect2"> <h3 id="_site_yml의_파괴된_에피소드_세션_2_bakery_plugin">site.yml의 파괴된 에피소드 (세션 2, bakery-plugin)</h3> <div class="paragraph"> <p>이 방법도 재난에서 비롯됩니다. 프로젝트에서`bakery-gradle`, 세션 2에서, 저는 에이전트에게 파일을 수정하도록 요청합니다`site.yml`. 에이전트는 파일이 버전 관리됐는지 확인하지 않고 하나를 만든다`Write`내용이 완전히 덮어쓰는. 결과 : 실제 토큰(Firebase API 키, 배포 비밀)은 가짜 플레이스홀더로 대체됩니다. 파일은 git에 있지 않았습니다 — 그것은`.gitignore`비밀을 보호하기 위해.</p> </div> <div class="paragraph"> <p>백업 없이. 없이`git restore`가능. 저는 막혔습니다. 수동으로 구성 파일을 다시 만들어야 하고, 비밀번호 관리자에서 토큰을 찾아서 모두 다시 붙여야 합니다.</p> </div> <div class="paragraph"> <p>이 좌절에서 비롯되는 것이다<strong>절대 규칙 1b</strong>(Note: The output is a single space character, as the input text to translate was a space after the colon, and spaces are language-neutral in translation.)</p> </div> <div class="paragraph"> <p><em><em>_ <strong>절대 짓밟지 마라</strong>하나의 구성 파일과 하나의`Write`완료될 때 하나의`Edit`부분만으로 충분합니다.<strong>절대 교체하지 마세요</strong>민감한 값을 가짜 값으로 대체합니다.<strong>확인 <code>git check-ignore</code> 그리고 `git ls-files</strong>어떤 수정도 하기 전에. </em>_</em></p> </div> <div class="paragraph"> <p>이 규칙은 오늘날 모든 내 파일의 대리석에 새겨져`AGENT.adoc` et `INDEX.adoc`네 개 프로젝트에서 실제 오류가 발생하여 수작업에 한 시간을 소요했습니다.</p> </div> </div> <div class="sect2"> <h3 id="_마크다운_애스키도크_마이그레이션_세션_1_cheroliv_com">마크다운 → 애스키도크 마이그레이션 (세션 1, cheroliv.com)</h3> <div class="paragraph"> <p>2026년 4월 25일, 위에`cheroliv.com`, 나는 근본적인 결정을 내린다: 마크다운의 전체 거버넌스를 AsciiDoc으로 전환한다. 미적이지 않다. 기능적이다. AsciiDoc은 LLM이 더 잘 읽을 수 있는 의미적 구조를 제공한다: 계층적 섹션, 타입이 지정된 테이블, 어드몬트먼트(<code>NOTE</code>, <code>WARNING</code>, <code>CAUTION</code>), 기계가 읽을 수 있는 문서 속성</p> </div> <div class="paragraph"> <p>세션 1의`cheroliv.com`구조를 공식화 :</p> </div> <div class="ulist"> <ul> <li> <p>변환`AGENTS.md` en <code>AGENT.adoc</code></p> </li> <li> <p>전문 에이전트 생성 :`CODER.adoc`, <code>SCRUM_MASTER.adoc</code>, <code>PLANTUML_DESIGNER.adoc</code></p> </li> <li> <p>Eager/Lazy 구조 생성 :`INDEX.adoc`, <code>SESSIONS_HISTORY.adoc</code>, <code>AGENT_SESSION_MANAGER.adoc</code>, <code>SESSION_CHECKLIST.adoc</code>, <code>PROCEDURES.adoc</code></p> </li> </ul> </div> <div class="paragraph"> <p>단일 커밋 :`90975e9 refactor: migrate agent governance from Markdown to AsciiDoc`. 그리고 사이트는 계속 작동합니다.</p> </div> <div id="diag-timeline" class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam handwritten false title 세션의 발전 — 세션 1부터 150+까지 legend top |= Couleur |= Projet | | <#4CAF50> | cheroliv.com | | <#2196F3> | plantuml-plugin | | <#FF9800> | bakery-plugin | | <#9C27B0> | magic-stick | endlegend concise "활성 세션" as S @S 0 is ".md 원시" 1 is "마이그레이션 AsciiDoc" 10 is "Eager/Lazy 형식화된" 62 is "안전 규정\n(site.yml)" 87 is "크래킹\n맥락" 109 is "최적화 -60% 토큰" 133 is "133 세션 240 테스트 통과" S@0 -> S@1 : Session 1\n(cheroliv.com) S@1 -> S@10 S@10 -> S@62 : Session 62\n(plantuml-plugin) S@62 -> S@87 : Session 87\n(Cry 4 help) S@87 -> S@109 : Session 109\n(API Key Pool) S@109 -> S@133 : Session 133\n(Aujourd'hui) @enduml</pre> </div> </div> <div class="paragraph"> <p>위 타임라인은 실제 진행 상황을 보여줍니다. 전환점은 세션 87이며, 이때 반복적인 재컨텍스트화의 좌절감이 허용 한계를 초과하고, Eager/Lazy 방법은 더 이상 아이디어가 아니라 필수 조건이 됩니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_전략_eagerlazy_심층">전략: Eager/Lazy 심층</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_철학_인지에_적용된_컴퓨터_캐시">철학 :인지에 적용된 컴퓨터 캐시</h3> <div class="paragraph"> <p>내 접근 방식은 컴퓨터 캐시 관리로부터 직접 영감을 받았습니다. 모든 것이<strong>비판적이며 자주 사용되는</strong>즉시 접근 가능해야 (<strong>열정적인</strong>). 모든 것이<strong>문맥적 혹은 대용량</strong>요청 시 로드해야 함<strong>게으른</strong>).</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6676%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">열정적인 (대시보드)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">느긋한 (소유자 매뉴얼)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>크기</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">< 100 줄, < 10k 토큰</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">무제한, 상세한</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>로딩</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">자동, 세션 시작 시</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">에이전트의 요청에 따라</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>내용</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">절대적인 규칙, 현재 진행 중인 임무, 위급한 상태</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">세션 아카이브, 전체 기록, 상세 절차, 기술 참조</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>역할</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">즉시 에이전트의 방향을 잡아라</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">깊은 맥락의 질문에 답하기</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_eager_파일_대시보드">Eager 파일 : 대시보드</h3> <div class="paragraph"> <p>이 파일들은 각 프로젝트의 루트에 위치하고 에이전트에 의해 각 세션 시작 시 자동으로 로드됩니다. 이들은 을 형성<strong>대시보드</strong>-- 중요 정보, 즉시 접근 가능.</p> </div> <div id="diag-eager-lazy" class="listingblock"> <div class="content"> <pre>@startuml skinparam defaultTextAlignment center skinparam wrapWidth 200 package "프로젝트 루트 (Eager - 자동 로드)" { component "<b>AGENT.adoc</b> 절대 규칙 구조 및 관례" as AGENT component "<b>PROMPT_REPRISE.adoc</b> N 세션의 미션 N-1 요약" as PROMPT component "<b>INDEX.adoc</b> 진입점 규칙 + 세션" as INDEX component "<b>*_ESSENTIALS.adoc</b>\n중요한 비즈니스 컨텍스트" as ESS } package ".agents/ (Lazy - 요청 시 로드)" { component "<b>sessions/N-*.adoc</b>\n상세 기록\n결정 및 출력" as SESS component "<b>SESSIONS_HISTORY.adoc</b> 요약 테이블 날짜/유형/점수" as HIST component "<b>PROCEDURES.adoc</b> 세션 종료 템플릿 6단계" as PROC component "<b>*_REFERENCE.adoc</b> 완전한 아키텍처 기술 참조" as REF component "<b>COMPLETED_TASKS_ARCHIVE</b> 완료된 작업 월별" as ARCH component "<b>AGENT_MODUS_OPERANDI.adoc</b> 전략 문서 방법론" as MOD component "<b>*_REFERENCE.adoc</b> Boot tests, A/B partition 특정 컨텍스트" as SPEC } AGENT --> PROMPT : "참고문헌" AGENT --> INDEX : "참고문헌" INDEX --> SESS : "색인하다" INDEX --> HIST : "색인하다" INDEX --> PROC : "참조" INDEX --> ARCH : "참조" INDEX --> REF : "참조" PROMPT --> SESS : "아카이브 N-1" PROMPT --> ESS : "비즈니스 컨텍스트 N" @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>AGENT.adoc</strong>-- 마스터 파일. 에`cheroliv.com`, 그것은 200줄이며 포함합니다:</p> </div> <div class="ulist"> <ul> <li> <p>프로젝트의 절대적인 규칙 (허가 없이 커밋 금지,`rm`확인 없이)</p> </li> <li> <p>프로젝트 구조와 코드 컨벤션</p> </li> <li> <p>필수 명령어 (<code>./gradlew serve</code>, <code>./gradlew test</code>)</p> </li> <li> <p>에픽들과 제품 백로그(우선순위된 사용자 스토리)</p> </li> <li> <p>전방위적 품질 기준 (접근성, 반응형, 호환성)</p> </li> </ul> </div> <div class="paragraph"> <p>위에`bakery-plugin`, 규칙 0는 다릅니다 :<strong>./gradlew -q publishToMavenLocal` 소스 코드를 수정할 때마다 필수입니다.</strong>. 로컬 JAR을 다시 패키징하지 않고 플러그인을 테스트했기 때문에 아직 패키징되지 않은 코드를 디버깅하는 데 한 시간을 허비하게 되었다.</p> </div> <div class="paragraph"> <p><strong>PROMPT_REPRISE.adoc</strong>-- 현재 세션의 임무. 각 세션 종료 시 업데이트되며, 다음을 포함합니다:</p> </div> <div class="ulist"> <ul> <li> <p>세션 번호와 우선 순위 임무</p> </li> <li> <p>이전 세션의 요약 (완료된 내용, 아직 해야 할 일)</p> </li> <li> <p>현재 세션의 수락 기준</p> </li> <li> <p>특정 기술 알림</p> </li> </ul> </div> <div class="paragraph"> <p><strong>.agents/INDEX.adoc</strong>-- 진입점입니다. 절대 규칙, 최근 세션, 그리고 무엇보다<strong>프로젝트 포트폴리오</strong>같은 방법론으로 관리되고 있습니다. 현재까지, 다섯 개의 프로젝트가 여기에 나열되어 있습니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- ---- | magic-stick | Session 23 | SCRIPT_VERIFICATION.adoc | 2026-04-27 | | bakery-gradle | Session 11 | TEST_COVERAGE_ANALYSIS | 2026-04-27 | | cheroliv.com | Session 9 | TEST_COVERAGE_ANALYSIS | 2026-04-27 | | plantuml-gradle| Session 133| TEST_COVERAGE_ANALYSIS | 2026-04-23 | | jhipster-gradle-plugins | Session 1 | TEST_COVERAGE_ANALYSIS | 2026-04-28 | ---- **`*_ESSENTIALS.adoc`** -- 최근 추가된 사항(세션 109, plantuml-plugin)으로 Eager 컨텍스트를 더욱 최적화하기 위해, API 키 풀에 비즈니스 컨텍스트 200줄을 로드하는 대신, 필수 50줄만 로드하고 나머지 150줄은 LAZY 상태로 안에`*_REFERENCE.adoc`. 측정된 결과: 통과**~25k 토큰 EAGER부터 ~10k 토큰까지**(60% 증가). 이제 더 이상 에너지 소모되는 알림이 필요하지 않다. ==== 누락된 연결고리 : `opencode.json 나는 문서화하는 것을 거의 잊어버릴 뻔한 사실을 고백해야 한다. 이 모든 .adoc 파일 위에 작동에 필수적인 아주 작은 JSON 파일이 있다. 그의 이름은`opencode.json`그리고 그는 여섯 줄입니다. 글자 그대로 여섯 줄입니다. [source,json] ---- { "$schema": "https://opencode.ai/config.json", "instructions": [ "AGENT.adoc" ] } ---- 이 파일은 Opencode에게 말한다: « 시작 시, 로드 `AGENT.adoc`자동으로. » 그 없이는 에이전트는 기사 시작 부분에서 제가 설명한 것처럼 빈 페이지와 같습니다. 그 있으면 에이전트는 이미 손에 쥔 절대 규칙, 프로젝트 아키텍처, 그리고 필수 명령을 가지고 있습니다 — 저조차도 인사하기 전에. 이 파일의 중요성을 우연히 발견했습니다. 위`bakery-plugin`, 존재하지 않았습니다. 나는 왜 에이전트가 이 프로젝트에서 다른 프로젝트들에 비해 체계적으로 더 « 잃어버린 » 상태였는지 궁금했다. 절대 규칙들은 잘 들어 있었다.`AGENT.adoc`— 하지만`AGENT.adoc`절대 충전되지 않았습니다. 에이전트는 내가 읽으라고 지시한 내용만 읽었고, 매 세션마다 수동으로 수행했습니다. 이것은 세션 11의`bakery-plugin`quand 나는 ...의 부재를 깨달았을 때`opencode.json`. 저는 그것을 만들었습니다 — 그리고 세션 12은 다른 세션들과 마찬가지로 시작되었습니다. 이 파일은 지금 나에게 너무나 명백해서 그를 전혀 생각하지 않는다. 도구를 너무 잘 아는 개발자가 흔히 저지르는 실수다. 오늘은 나는 그것을 체계적으로 *먼저* 만든다.`AGENT.adoc`. 이것은 첫 번째 돌이다. ==== 의 이중성 `INDEX.adoc 또 명시할 가치가 있는 또 다른 미묘함 :`INDEX.adoc`에 산다`.agents/`— 제가 `LAZY`라고 제시한 폴더. 하지만 저는 모든 테이블에서 그것을 `EAGER`라고 등록합니다. 여기에는 명백한 긴장이 있습니다. 현장 현실 : 파일들`.agents/INDEX.adoc`자동으로 시작 시에 잘 로드되며, 그와 마찬가지로`AGENT.adoc` et `PROMPT_REPRISE.adoc`그들은 안에`.agents/`조직상의 이유로 — 루트를 침범하지 않기 위해 — 하지만 그들의 동작은 EAGER. 위`plantuml-plugin`, `INDEX.adoc`200줄에 *완전한* 절대 규칙과 그 기록(지난 세션의 교훈)과 함께, EPIC과 점수, 그리고 프로젝트 포트폴리오가 포함되어 있습니다. 이것은 에이전트가 '현재 진행 상황'을 알기 위해 참조하는 문서입니다. 위`bakery-plugin`, 그는 로드맵과 최근 세션으로 150줄을 만든다. 의도적인 중복 사이`AGENT.adoc` et `INDEX.adoc`놀라울 수 있습니다. 절대 규칙은 양쪽에 존재합니다. 왜 ? 왜냐하면它们... : 안에`AGENT.adoc`, 그들은 *설명적인* (규칙의 이야기, 배운 교훈); 안에서`INDEX.adoc`,그녀들은 *집행적인* (벌거숭이 규칙, 정당화 없이, 빠른 참고를 위해). 에이전트는 읽는다`AGENT.adoc`한 번 *comprendre*를 위해; 그는 다시 읽는다`INDEX.adoc`각 세션에 *적용*하기 위해. 두 가지 사용법, 두 가지 형식. [plantuml, format=svg, id=diag-dualite-agent-index, alt="Comparaison entre AGENT.adoc (narratif) et INDEX.adoc (exécutif)"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title 이중성 AGENT.adoc ←→ INDEX.adoc left to right direction rectangle "AGENT.adoc (근원 — EAGER)" as AGENT #E3F2FD { rectangle "📖 **서사 형식** 규칙의 스토리텔링 배운 교훈, 맥락" as NARR rectangle "🏗️ **완전한 아키텍처** 프로젝트 구조, 구성 요소 상세한 US 백로그" as ARCHI rectangle "📋 **설명 규칙** 왜 규칙이 존재하는가 사건 기록" as EXPL } rectangle "INDEX.adoc\n(.agents/ — 열망하는)" as INDEX #E8F5E9 { rectangle "⚡ **실행 형식** 규칙 자체만, 정당화 없이 빠른 상담" as EXEC rectangle "📊 **Roadmap & EPICs**\n요약 표\n진행 상황, 점수, 우선순위" as ROAD rectangle "🌐 **프로젝트 포트폴리오** 횡단 뷰 5개의 동기화된 프로젝트" as PORT } AGENT --> INDEX : "에이전트가 AGENT.adoc를 읽음\n이해하기 위해 한 번" INDEX --> AGENT : "Agent relit INDEX.adoc\n각 세션에 **적용하기 위해**" note bottom of AGENT Taille max : 200 lignes end note note bottom of INDEX Taille max : 200 lignes Source de vérité en cas de divergence end note @enduml ---- 이 명시적인 중복은 설계 선택입니다. 이는 EAGER 토큰에서 약 50줄을 추가로 소비하지만 — 에이전트가 항상 규칙을 눈앞에 두도록 보장합니다. 여기에는 즉각적인 순종을 촉진하는 간결한 형식도 포함됩니다. === LAZY 파일: 소유자 매뉴얼 이 파일들은 ...에 존재합니다`.agents/`그리고 에이전트가 필요할 때만 읽힙니다. 그들은 방법의 진정한 가치를 구성하며, 왜냐하면 그들은 현재 맥락을 오염시키지 않고 프로젝트의 지식을 축적하기 때문이다. [plantuml, format=svg, id=diag-agents-tree, alt="Arborescence complète du dossier .agents/"] ---- @startuml skinparam folderBackgroundColor #E3F2FD skinparam folderBorderColor #1565C0 skinparam fileBackgroundColor #FFF3E0 skinparam fileBorderColor #EF6C00 folder ".agents/" as ROOT { file "INDEX.adoc\n(EAGER -- 200 줄)" as IDX #E8F5E9 file "AGENT_SESSION_MANAGER.adoc 템플릿 세션" as ASM file "SESSION_CHECKLIST.adoc (변경 시점)" as CHK file "PROCEDURES.adoc (6 단계 + LAZY/EAGER)" as PRO file "SESSIONS_HISTORY.adoc (모든 세션)" as HIS folder "세션/" as SESS { file "1-일-마이그레이션.adoc" as S1 file "109-정식화-게으른.adoc" as S109 #FFECB3 file "133-epic11-article.adoc" as S133 file "... +130 다른" as SMORE } folder "아카이브/" as ARCH { file "COMPLETED_TASKS_2026-04.adoc" as CTA file "SESSIONS_HISTORY_83-95.adoc" as SHIST folder "세션_요약/" as SUM { file "SESSION_64_SUMMARY.adoc" as SU64 file "SESSION_73_SUMMARY.adoc" as SU73 file "..." as SUMORE } folder "프롬프트_아카이브/" as PARCH { file "PROMPT_REPRISE_S65.adoc" as PR65 file "PROMPT_REPRISE_S75.adoc" as PR75 file "..." as PMORE } } } IDX --> SESS : "색인" IDX --> HIS : "색인" IDX --> ARCH : "참조" note right of S109 Session 109 = Formalisation stratégie LAZY/EAGER Token : ~25k → ~10k end note @enduml ---- 위 트리 구조는 폴더의 실제 구조를 보여줍니다.`.agents/`위에`plantuml-plugin`, 가장 성숙한 프로젝트. 세 층의 깊이에 주의하세요: 루트 파일(메타데이터), 폴더`sessions/`(연대순 아카이브), 그리고 폴더`archives/`(집계 및 요약). 이 깊이는 단순한 TODO 파일의 거버넌스를 무엇인가로 변환한다.**완전한 조직 기억**. **.agents/sessions/{N}-{titre}.adoc**-- 각 세션의 상세한 아카이브. 현재 : * `plantuml-plugin` : **133개의 세션이 보관되었습니다**(세션 1부터 133까지) * `bakery-plugin`:**11 세션** * `magic-stick`:**23 세션** * `cheroliv.com`:**9회 공식 세션**+ 7개의 사전 시스템 세션이 역으로 재구성되었습니다 각 아카이브에는 세션의 전체 컨텍스트, 이루어진 결정, 발생한 문제와 그 해결, 실행된 명령과 그 출력이 포함됩니다. **.agents/SESSIONS_HISTORY.adoc**-- 모든 세션의 점수를 요약한 표. 예시에서`cheroliv.com`: ---- | -6 | 2025-05 | chore | Initialisation projet Gradle/JBake | 7/10 | 1 | 2026-04-25 | chore | Migration gouvernance agent | 8/10 | 7 | 2026-04-27 | debug/fix | Correction publishSite | 9/10 | 8 | 2026-04-27 | analyse | Analyse article 0108 | 7/10 **.agents/COMPLETED_TASKS_ARCHIVE_{월}.adoc**-- 완료된 작업들을 월별로 아카이브하여 활성 백로그를 과부하시키지 않도록 합니다. 사용자 스토리가 완료되면 여기서 이동합니다. 백로그는 읽기 쉬운 상태를 유지하며, 활성 항목은 최대 10개입니다. **.agents/PROCEDURES.adoc**-- 세션 종료 절차의 상세 템플릿. 길지만, 에이전트가 방법을 배울 때 한 번만 읽음. 이후 절차는 기계적이 된다. **.agents/AGENT_MODUS_OPERANDI.adoc**-- 전략적 문서 전체. 위에`plantuml-plugin`, 이 파일은**900+ 줄**그리고 실제로 불리는`AGENT_METHODOLOGIES.adoc`— 나는 이 기사를 쓰는 동안과 실제로 적용하는 사이에 이름을 바꾸었다. 이런 종류의 네이밍 차이는 진화하는 수공예 시스템에서는 피할 수 없다. 중요한 것은 이름 짓기 관습이다: 만약 파일이 *메서드*를 문서화한다면, 그것은 ...로 시작한다.`AGENT_`또는 명시적 접두사. Eager/Lazy 방법론을 문서화하고, 따라야 할 패턴과 피해야 할 안티패턴을 설명합니다. 이는 LAZY이기 때문인데, 에이전트는 매 세션마다 전체 전략을 다시 읽을 필요가 없고, 오직 애매함이 있을 때만 그렇게 한다. **`*_REFERENCE.adoc`** -- 프로젝트에 특화된 기술 참조. 에`magic-stick`, 두 개의 LAZY 밀집 파일 : * `AB_PARTITION_REFERENCE.adoc`(147줄) -- A/B 파티션 아키텍처 GPT, 스크립트`update-system.sh`, 추정 크기, 롤백 메커니즘 * `BOOT_TEST_REFERENCE.adoc`(144 줄) -- QEMU + VNC를 이용해 물리적 하드웨어 없이 ISO 부팅을 테스트하는 절차, BIOS/UEFI 체크리스트, CI/CD 제한 위`plantuml-plugin` : * `ARCHITECTURE.adoc`(134줄) -- 11개의 데이터 클래스 구조, 주의 사항 (피해야 할 함정), 최적화된 테스트 명령어 * `API_KEY_POOL_REFERENCE.adoc`-- 키 풀의 전체 세부 정보 (LAZY 동안`ESSENTIALS`이다 EAGER) == 전문 에이전트 : 가상 팀 거버넌스는 정적인 파일에만 한정되지 않습니다. 저는 일부를 형식화했습니다**전문 에이전트들의 역할**전용 LAZY 파일에서, 작업 유형에 따라 예상되는 워크플로우를 정의합니다. |=== |에이전트 |파일 |역할 |프로젝트 |**코더** |`CODER.adoc` |FTL/CSS/JS 구현, 시맨틱 태그, 접근성 기준 |cheroliv.com |**스크럼 마스터** |`SCRUM_MASTER.adoc` |미국 계획, 하위 작업으로 분할, 의존성 감지 |cheroliv.com |**PlantUML 디자이너** |`PLANTUML_DESIGNER.adoc` |다이어그램 작성, PUML 구문, JBake 통합 |cheroliv.com |=== 파일`CODER.adoc`위`cheroliv.com`포함하는 구체적인 규칙이 있습니다: _하나`<h1>`페이지당_, _경로에 접두사 추가하기`${content.rootpath}`_, _언어를 선언`<html lang="${content.lang!"fr"}">`_. 이러한 협약은 한 번 작성되면 에이전트가 세션 1부터 자동으로 준수합니다. 파일`SCRUM_MASTER.adoc`산출물의 구조를 규정한다 :**목표**, **작업**(할당이 있는 좌표),**수용 기준**, **위험**. 행동 계획을 요청할 때, 에이전트는 내가 요청하지 않았음에도 이 구조를 생성합니다. 거버넌스**프로그램**요원. ==== 전문화된 에이전트가 필수적이 될 때 전문 에이전트의 생성은 자연스러운 곡선을 따릅니다. 프로젝트 초반에는 필요하지 않습니다 —`AGENT.adoc`충분합니다. 하지만 프로젝트가 커질 때 (예를 들어, 20세션을 넘어) 두 가지 신호가 당신을 경고해야 합니다 : 1. 에이전트는 서로 다른 두 분야의 규칙을 혼합합니다(예: PlantUML 구문과 CSS 규칙) 2. 당신은 이미 5번 설명한 관습에 대해 에이전트를 수정하는 데 더 많은 시간을 보냅니다. 위`cheroliv.com`, 세션에 도착했습니다... 1. 예, 처음부터. 왜냐하면 이 프로젝트는 세 가지 언어(`FTL`, `CSS`, `JS`)로 이루어진 웹사이트이며, `AsciiDoc` 콘텐츠와 `PlantUML` 다이어그램이 포함되어 있기 때문입니다 — 세 가지 분야가 전혀 관련이 없습니다. `CODER` 에이전트는 글꼴 크기와 미디어 쿼리를 알아야 하며, `PLANTUML_DESIGNER` 에이전트는 문법을 알아야 합니다.`@startuml`. 분리 없이, CODER 에이전트가 다이어그램을 제시해 주었고, 반대도 마찬가지였다. 혼란. 위에`jhipster-gradle-plugins`, 저는 Gradle 플러그인 개발에 맞춘 두 개의 전문화된 에이전트를 만들었습니다 :`PLUGIN_DEVELOPER.adoc` et `BACKLOG_MANAGER.adoc`. 첫 번째는 Kotlin/Gradle의 모든 규약을 인코딩합니다(아니오`!!`, 모델에 대한 데이터 클래스,`@TaskAction`작업들에 대해). 두 번째는 알고 있다`persistence`안정적이어야만`assistant`개발을 시작하지 않는다 — 모노레포에서의 중요한 의존성 실수하지 말아야 할 것 : 너무 많은 에이전트를 너무 일찍 만드는 것`plantuml-plugin`108번째 세션을 기다린 후 API 키 풀을 위한 전문 에이전트를 공식화했습니다. 그때까지 비즈니스 컨텍스트는`AGENT.adoc`. 경험칙 : 전문 에이전트는 그 업무 분야가 문서 100줄을 초과할 때 정당화된다. ==== 세션 명명 규칙 사소해 보이는 세부 사항이지만 100 세션에 도달하면 중요해집니다. 아카이브 파일 이름을 어떻게 지어야 하나요? 나는 힘들게 배웠는데, 하나의 관습이 필요하다는 것을 — 네 개의 프로젝트, 네 가지 다른 형식으로 시작했고, 나는 길을 잃었다. 오늘 내가 확립한 관습은:</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre></pre> </div> </div> <div class="paragraph"> <p>{N}-{type}-{sujet-kebab-case}.adoc</p> </div> <div class="listingblock"> <div class="content"> <pre>구체적인 예시 : * `1-chore-migration-gouvernance-agent.adoc`— 세션 1, 타입 안무 * `10-solidification-tests.adoc`— 세션 10, 명시적 타입이 없음 (주어가 충분함) * `036-debug-graphify-symlink-epic9.adoc`— 세션 36, 3자리 숫자로 정렬 세션 번호가 주요 정렬 기준입니다. 3자리 숫자(001, 036, 133)를 사용하는 프로젝트는 99를 초과할 때 사전식 정렬 문제를 피합니다. 이것이 제가 지금부터 사용하는`magic-stick`:`001-init-projet.adoc`, `036-debug-graphify-symlink-epic9.adoc`. 타입은 선택 사항이며, 세션의 키워드(debug, feature, refactor, docs, chore, test)에서 파생됩니다. kebab-case 형식의 주제는 가장 중요한 부분이며, 파일을 열지 않고 세션을 찾을 수 있어야 합니다. «통합 테스트의 타임아웃을 수정한 세션은 어느 것이었나요?», 답은`124-fix-timeout-integration-test.adoc`. 재구성된 역사적 세션(거버넌스 이전에 태어난 프로젝트)에는 음수를 사용합니다. 위`cheroliv.com`, 세션 -6부터 0까지는 프로젝트의 전체 사전 거버넌스 역사를 다룹니다. 그리고 문서화되지 않거나 잃어버린 세션에 대해, 나는 항목을 만든다`SESSIONS_HISTORY.adoc`해당하는 아카이브 없이, 점수가 있음`?`. 그거는 솔직해 보이는 것보다 더 솔직하다. [plantuml, format=svg, id=diag-naming-convention, alt="Arbre de décision pour le nommage des fichiers de session"]</pre> </div> </div> <div class="paragraph"> <p>@startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 200</p> </div> <div class="paragraph"> <p>title 세션 명명 규칙 start</p> </div> <div class="paragraph"> <p>:Une session se termine; note right: Trigger "세션 종료"</p> </div> <div class="paragraph"> <p>if (Session antérieure\nà la gouvernance ?) then (oui) :Numéro <strong>NÉGATIF</strong>\n-6, -5 …​ 0; note right: Historique\nreconstitué :Suffixe : reconstitution; else (non) :Numéro <strong>POSITIF</strong>\nsur 3 chiffres si > 99; note right: 001, 036, 133\npour le tri lexicographique</p> </div> <div class="literalblock"> <div class="content"> <pre>:Détecter le **TYPE**; if (Mots-clés trouvés ?) then (oui) :debug / feature / refactor\ndocs / chore / test; else (non) :Omettre le type\n(le sujet suffit); endif</pre> </div> </div> <div class="literalblock"> <div class="content"> <pre> :Formuler le **SUJET** en kebab-case; note right Ex: fix-timeout-integration-test Doit permettre de retrouver sans ouvrir le fichier end note endif</pre> </div> </div> <div class="paragraph"> <p>note right • 1-chore-migration-gouvernance.adoc • 036-debug-graphify-symlink.adoc • 124-fix-timeout-integration-test.adoc • 133-epic11-article-blog-kg.adoc end note</p> </div> <div class="paragraph"> <p>if (Session documentée ?) then (oui) :Créer archive dans sessions/; :Ajouter ligne SESSIONS_HISTORY\navec score X/10; else (non) :Ajouter ligne SESSIONS_HISTORY\navec score <strong>?</strong>\n<strong>sans archive</strong>; note right: L’honnêteté\nplutôt que le vide endif</p> </div> <div class="paragraph"> <p>stop @enduml</p> </div> <div class="listingblock"> <div class="content"> <pre>==== TEST_COVERAGE_ANALYSIS.adoc` — 5단계 세부 분석 세션 종료 절차의 단계 5가 가장 미스터리합니다. 그것은 '업데이트'라고 말합니다.`TEST_COVERAGE_ANALYSIS.adoc`테스트가 추가되거나 수정되었습니다. » 하지만 이 파일은 어떤 모습인가요? 위`plantuml-plugin`, 몇 줄에서 완전한 구조로 진화했습니다. 다음은 그 안정화된 형태입니다: [source]</pre> </div> </div> </div> </div> </div> <h1 id="_analyse_de_couverture_de_tests" class="sect0">Analyse de Couverture de Tests</h1> <div class="sect1"> <h2 id="_suivi_des_tests">Suivi des Tests</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 20%;"> <col style="width: 20%;"> <col style="width: 20%;"> <col style="width: 20%;"> <col style="width: 20%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Classe de test</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Type</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tests</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Statut</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Dernière MAJ</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">PlantumlServiceTest</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">unit</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">45/45</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ PASS</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2026-04-23</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">ApiKeyPoolTest</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">integration</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">15/15</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ PASS</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2026-04-20</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_historique_par_session">Historique par Session</h2> <div class="sectionbody"> <div class="paragraph"> <p>| Session | Tests ajoutés | Tests modifiés | Couverture | 133 | 0 | 2 | 100% | 132 | 5 | 0 | 100%</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">----</p> <p class="tableblock">관심은 파일 자체에 있는 것이 아니라 — 변경된 사항을 <strong>기록</strong> 해야 하는 의무다. 이 단계를 거치지 않으면, 50번의 세션 후에 어떤 테스트가 무엇을 커버하는지 더 이상 알 수 없게 된다. 에이전트도 마찬가지다. 파일은 프로젝트 테스트 커버리지에 대한 단일 진실 원천이 된다.</p> <p class="tableblock">전통적인 테스트가 없는 프로젝트 (예:`magic-stick`bash 스크립트를 테스트하는), 5단계는 대체됩니다`SCRIPT_VERIFICATION.adoc`. 메커니즘은 같습니다 : 스크립트 유효성 검사 상태를 추적하는 파일입니다. 프로젝트에 맞게 5단계를 조정하되 절대 건너뛰지 마세요. 그것은 침묵적인 회귀를 방지하는 안전망입니다.</p> <p class="tableblock">만약 귀하의 프로젝트에 <strong>테스트가 전혀 없다</strong> — 단위 테스트도, 기능 테스트도, 스크립트도 없이 — 빈 파일을 만들어서 « 할 일: 테스트 전략 정의하기. » 라는 섹션을 추가하세요. 이는 미래의 자신에게 이 주제가 아직 다루어지지 않았음을 상기시켜 줄 책갈피입니다.</p> <p class="tableblock">[plantuml, format=svg, id=diag-session-flow, alt="Flux d’une session type avec Eager/Lazy et agents"] ---- @startuml skinparam backgroundColor #FEFEFE</p> <p class="tableblock">start</p> <p class="tableblock">:Début session; note right: L’agent est une page blanche</p> <p class="tableblock">:Chargement EAGER auto; note right * AGENT.adoc (règles absolues) * PROMPT_REPRISE.adoc (mission N) * INDEX.adoc (état projet) end note</p> <p class="tableblock">if (Mission claire ?) then (oui) :Exécution directe; else (non) :Charge LAZY sur demande; note right * SESSIONS_HISTORY.adoc (contexte passé) * sessions/{N-1}-<strong>.adoc (décisions) * *<em>REFERENCE.adoc (architechture) end note endif</p> <p class="tableblock">:Délégation agent spécialisé ?;</p> <p class="tableblock">if (CODER ?) then (oui) :Lit CODER.adoc; :Suit conventions FTL/CSS; elseif (SCRUM Master ?) then (oui) :Lit SCRUM_MASTER.adoc; :Structure livrable imposée; elseif (PlantUML ?) then (oui) :Lit PLANTUML_DESIGNER.adoc; :Syntaxe PUML + intégration; else (non) endif</p> <p class="tableblock">:Travail de la session;</p> <p class="tableblock">:Fin de session (trigger utilisateur);</p> <p class="tableblock">:Procédure 6 étapes; note right 1. Archive sessions/N-</strong>.adoc 2. Maj PROMPT_REPRISE.adoc (N+1) 3. Maj SESSIONS_HISTORY.adoc 4. Maj INDEX.adoc 5. Maj TEST_COVERAGE (si applicable) 6. Maj COMPLETED_TASKS_ARCHIVE.adoc end note</p> <p class="tableblock">:Checklist [✅] x 6;</p> <p class="tableblock">stop @enduml ----</p> <p class="tableblock">위쪽 다이어그램은 세션의 전체 생명 주기를 보여줍니다. 핵심 포인트는 EAGER 로드 후의 분기입니다: 미션이 충분히 명확해서 직접 실행할 수 있는 경우(80%의 경우)와, 애매함을 해결하기 위해 LAZY를 로드하는 경우(20%의 경우)입니다. 이러한 차별화가 토큰을 절약합니다.</p> <p class="tableblock">== 세션 종료 절차 : 황금 규칙</p> <p class="tableblock">=== 왜 그녀는 필수적인가?</p> <p class="tableblock">이 절차가 없으면 Eager/Lazy 전략은 무용지물이다. 이 절차가 세션의 작업을 지속 가능한 정보로 변환한다. 이 절차가 실행된다.<strong>사용자의 명시적 요청에 따라</strong>(키워드 : "세션 종료", "나는 떠나", 등등), 그리고 그녀는<strong>필수</strong>-- 예외도 없고, 누락도 없습니다.</p> <p class="tableblock">파일`SESSION_CHECKLIST.adoc`이상적인 세션 메트릭스를 정의합니다 :</p> <p class="tableblock">* 소요 시간 : 15-30분 * 수정된 파일 : 1-3 최대 * LLM 교환 : 5-10 메시지 * 컨텍스트 토큰 : < 50k</p> <p class="tableblock">세션을 변경해야 하는 징후는 다음과 같습니다 : _LLM이 이미 수정된 오류를 반복한다</em>, <em>3개 이상의 파일이 동시에 수정됨</em>, <em>대화가 50개 메시지 초과</em>. 황금 규칙 :<strong>2시간 동안 디버깅이 혼란스러운 한 번의 세션보다 20분짜리 5번의 세션이 더 좋다.</strong></p> <p class="tableblock">=== 6단계 흐름 (침묵으로)</p> <p class="tableblock">[plantuml, format=svg, id=diag-end-session-flow, alt="Flux de la procédure de fin de session"] ---- @startuml skinparam defaultTextAlignment center skinparam wrapWidth 200 skinparam activityBackgroundColor #E3F2FD</p> <p class="tableblock">start :L’utilisateur dit "세션 종료"; note right: Mots-clés déclencheurs</p> <p class="tableblock">:Agent détecte le trigger;</p> <p class="tableblock">:Étape 1\nCréer archive\n`.agents/sessions/N-<strong>.adoc`; note right: Tout le contexte de la session</p> <p class="tableblock">:Étape 2\nMettre à jour\n`PROMPT_REPRISE.adoc`; note right: Mission N + critères d’acceptation N+1</p> <p class="tableblock">:Étape 3\nMettre à jour\n`SESSIONS_HISTORY.adoc`; note right: Ligne récap : # / Date / Type / Sujet / Score</p> <p class="tableblock">:Étape 4\nMettre à jour\n`INDEX.adoc`; note right: État courant, roadmap, fichiers modifiés</p> <p class="tableblock">:Étape 5\nMettre à jour\n`TEST_COVERAGE_ANALYSIS.adoc`; note right: Si tests ajoutés ou modifiés</p> <p class="tableblock">:Étape 6\nMettre à jour\n`COMPLETED_TASKS_ARCHIVE.adoc`; note right: Archiver tâches terminées</p> <p class="tableblock">:Afficher la checklist de confirmation; note right: Vérifier que chaque [✅] est mérité</p> <p class="tableblock">stop @enduml ----</p> <p class="tableblock">=== 150+ 세션의 결과</p> <p class="tableblock">이 절차를 내 네 개 프로젝트에 체계적으로 적용했을 때 결과는 다음과 같습니다:</p> <p class="tableblock"><strong>plantuml-plugin</strong>:</p> <p class="tableblock">* <strong>133 세션</strong>프로젝트 시작 이래 * <strong>240/240 테스트 PASS</strong>(100% 커버리지) — EPICs 1-7 완료 * <strong>57개의 Cucumber BDD 시나리오</strong>검증된 * 실제 오류에서 발생한 구성 파일 안전 규칙 (Session 2 bakery-plugin)</p> <p class="tableblock"><strong>베이커리-플러그인</strong> :</p> <p class="tableblock">* <strong>11 세션</strong>두 주 안에 * Supabase → Firebase 마이그레이션 완료 (9개 테스트 수정됨) * EPIC 6 (publishProfile)는 프로덕션에서 기능적으로 작동합니다 * 규칙 0이 생성되었습니다:`publishToMavenLocal`각 수정 후 필수</p> <p class="tableblock"><strong>마법 스틱</strong>:</p> <p class="tableblock">* <strong>23 세션</strong>Xubuntu 라이브 시스템을 A/B 파티션으로 구성하려면 * 세션 10에서 생성된 첫 번째 ISO * 공식화된 QEMU + VNC 부팅 테스트 (144줄의 LAZY 문서) * CI/CD SourceForge 기능적인</p> <p class="tableblock"><strong>cheroliv.com</strong>:</p> <p class="tableblock">* <strong>9개의 공식 세션</strong>+ 프리-시스템 세션 7개의 재구성 * Article 0101 (OpenCode PATH) 게시됨 * 제0108조 (이것)는 분석 후 재작성되었습니다 * 마크다운에서 애스시도크로 이전된 완전한 거버넌스</p> <p class="tableblock">=== 최종 체크리스트</p> <p class="tableblock">6단계를 침묵적으로 실행한 후, 에이전트는 확인 체크리스트를 표시해야 합니다 :</p> <p class="tableblock">----</p> <p class="tableblock">✅ Procédure de fin de session exécutée 📋 Checklist :</p> <p class="tableblock"><strong>절대적인 규칙</strong>: 어떤 단계도 표시할 수 없습니다`[✅]<code>파일이 실제로 수정되고 검증되지 않은 경우</p> <p class="tableblock">== Bootstrap 가이드: 1일 차, 세션 0</p> <p class="tableblock">당신은 그 방법에 확신을 가지고 있습니다. 그것을 새로운 프로젝트에 적용하고 싶습니다. 어디서부터 시작해야 할까요?</p> <p class="tableblock">나는 그 순간을 2026년 4월 28일에 경험했다. 나는 Opencode를 연다 위에`jhipster-gradle-plugins</code>, 저의 JHipster Gradle 플러그인 두 개의 모노레포. 이미 존재하는 프로젝트입니다 — 코드가 거기에 있고, Gradle 작업들이 정상 동작합니다. 하지만 에이전트 거버넌스 ? 제로. 빈 페이지.처럼`plantuml-plugin`그의 세션 1에, 몇 달 전에.</p> <p class="tableblock">여기 제가 따르는 정확한 절차가 있고, 앞으로 모든 새로운 프로젝트에 대해서도 이 절차를 따를 것입니다. 순서를 잘 살펴보세요 — 이것이 중요합니다.</p> <p class="tableblock">[plantuml, format=svg, id=diag-bootstrap, alt="Flux de bootstrap en 6 étapes pour initialiser la gouvernance agent sur un nouveau projet"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 250 skinparam activityBackgroundColor #E8F5E9</p> <p class="tableblock">title Bootstrap 거버넌스 — 1일차, 세션 0 start :Étape 0\nCréer <strong>opencode.json</strong>\n(6 lignes, instructions: AGENT.adoc); note right: Le pont qui charge\nAGENT.adoc automatiquement</p> <p class="tableblock">:Étape 1\nCréer les dossiers\n<strong>mkdir -p .agents/sessions/ .agents/archives/</strong>; note right: Les conteneurs vides\navant que l’agent écrive dedans</p> <p class="tableblock">:Étape 2\nCréer <strong>AGENT.adoc</strong>\n(200 lignes, règles absolues); note right: Le fichier maître\nStructure minimale v1</p> <p class="tableblock">:Étape 3\nCréer <strong>PROMPT_REPRISE.adoc</strong>\nMission session 1 (max 70 lignes); note right: Ce que l’agent doit\nfaire à la prochaine session</p> <p class="tableblock">:Étape 4\nCréer <strong>.agents/INDEX.adoc</strong>\nRègles exécutives + roadmap; note right: Point d’entrée EAGER\ndans le dossier LAZY</p> <p class="tableblock">:Étape 5\nCréer les fichiers LAZY structurants\n6 fichiers : SESSIONS_HISTORY, CHECKLIST, etc.; note right • SESSIONS_HISTORY.adoc • SESSION_CHECKLIST.adoc • PROCEDURES.adoc • AGENT_SESSION_MANAGER.adoc • TEST_COVERAGE_ANALYSIS.adoc • Agents spécialisés (si besoin) end note</p> <p class="tableblock">:Étape 6\nAjouter le projet au Portefeuille\nMettre à jour TOUS les INDEX.adoc existants; note right: Maintenance transverse\nObligatoire mais fastidieuse</p> <p class="tableblock">:✅ Bootstrap terminé\nSession 1 prête; note right: 20 minutes investies\nDes centaines économisées</p> <p class="tableblock">stop @enduml ----</p> <p class="tableblock">=== 단계 0 : <code>opencode.json</code> 생성하기</p> <p class="tableblock">이것은 첫 번째 파일입니다. 아니요`AGENT.adoc`, 안`INDEX.adoc`.<code>opencode.json`먼저, 간단한 이유 때문에: 당신이 만든다면`AGENT.adoc`먼저, 자동으로 충전되는 다리를 만드는 것을 잊게 될 것입니다. 저는 이것을 …​에서 했습니다.`bakery-plugin</code>, 나는 내가 말하는 것이 무엇인지 안다.</p> <p class="tableblock">=== 단계 1: 폴더 생성</p> <p class="tableblock">[source,bash] ---- mkdir -p .agents/sessions .agents/archives ----</p> <p class="tableblock">빈 폴더 두 개`sessions/<code>각 세션의 아카이브를 받게 될 것입니다.`archives/`월별 COMPLETED_TASKS_ARCHIVE를 받게 됩니다. 이 폴더들은 에이전트가 거기에 쓰기를 필요로 하기 *전에</strong> 존재해야 합니다. 폴더와 파일을 동시에 생성해야 하는 에이전트는 조용히 실패할 수 있는 에이전트입니다.</p> <p class="tableblock">=== 단계 2: `AGENT.adoc</code> 생성 — 마스터 파일</p> <p class="tableblock">첫 번째 버전을 위한 최소 구조 (성장할 것입니다) :</p> <p class="tableblock">[source] ---- = {NOM_PROJET} — Directives Agent</p> <p class="tableblock">[CAUTION] ----</p> <p class="tableblock"><strong>의무 정지</strong>rm 전, Write, 삭제:</p> <p class="tableblock">1. 파일을 끝까지 읽어라 2. 확인 git ls-files 3. 확인 요청 4. 예"를 기다리다</p> <p class="tableblock">== 프로젝트</p> <p class="tableblock"><strong>이름</strong>…​ <strong>스택</strong>: …​ <strong>문서</strong>: AsciiDoc</p> <p class="tableblock">== 절대 규칙</p> <p class="tableblock">=== 0. 개발 환경</p> <p class="tableblock">필수 명령어…​</p> <p class="tableblock">=== 1. COMMITS/GIT</p> <p class="tableblock">공식적인 금지…​</p> <p class="tableblock">=== 1b. 구성 파일 — 절대 안전 규칙</p> <p class="tableblock">절대로 눌러서는 안 돼…​</p> <p class="tableblock">=== 2. 세션 종료 테스트</p> <p class="tableblock">금지령…​</p> <p class="tableblock">=== 3. 세션 종료 절차</p> <p class="tableblock">필수 6단계…​</p> <p class="tableblock">== 컨텍스트 관리 — LAZY/EAGER</p> <p class="tableblock">EAGER 파일 / LAZY 파일…​</p> <p class="tableblock">이 최소 템플릿은 에이전트가 시작할 수 있게 해줍니다. 풍부한 버전 — 프로젝트 구조, 핵심 구성 요소, EPIC, 백로그 포함 — 은 에이전트가 이미 기본 규칙을 손에 쥐고 있을 때 세션 1에 제공될 것이며, 문서를 풍부하게 하는 데 도움을 줄 것입니다.</p> <p class="tableblock">=== 3단계: 만들기 <code>PROMPT_REPRISE.adoc</code> — 세션 1 미션</p> <p class="tableblock">다음과 같이 명시된 파일: « 이것이 세션 1, 정의해야 할 미션입니다. » 최대 70줄, 세션 0(부트스트랩 요약) 섹션과 세션 1(사용자와 정의할 우선순위) 섹션이 포함됩니다.</p> <p class="tableblock">=== 4단계: 생성 <code>.agents/INDEX.adoc</code> — 진입점</p> <p class="tableblock">절대 규칙(실행 버전)과 세션 테이블을 포함할 파일입니다. 부트스트래핑을 위해, 규칙 0부터 3까지를 간결한 형식으로 나열하고, 프로젝트 포트폴리오(새로운 프로젝트와 함께 이모지 🆕 포함)와 빈 로드맵(채워질 준비가 된)을 나열합니다.</p> <p class="tableblock">=== 5단계 : LAZY 구조화 파일 생성</p> <p class="tableblock">순서대로:</p> <p class="tableblock">1. <code>.agents/SESSIONS_HISTORY.adoc</code>— 세션 0만 있는 테이블 2. <code>.agents/SESSION_CHECKLIST.adoc</code>— 템플릿 « 세션 변경 시기 3. <code>.agents/PROCEDURES.adoc</code>— 6단계 전체 절차 + EAGER/LAZY 4. <code>.agents/AGENT_SESSION_MANAGER.adoc</code>— 아카이브 템플릿 5. <code>.agents/TEST_COVERAGE_ANALYSIS.adoc</code>— 테스트 추적 테이블, 처음에 비어 있음</p> <p class="tableblock">만약 당신의 프로젝트가 복잡한 비즈니스 도메인을 가지고 있다면 (예를 들어`jhipster-gradle-plugins`persistence/assistant 단일 레포와 함께, 지금 바로 전문 에이전트를 생성하세요 :</p> <p class="tableblock">1. <code>.agents/PLUGIN_DEVELOPER.adoc</code>— 코드 컨벤션과 의존성 경계 (플러그인인 경우) 2. <code>.agents/BACKLOG_MANAGER.adoc</code>— 계획 구조와 식별된 위험</p> <p class="tableblock">사용하지 않을 에이전트는 만들지 마세요. 인코딩할 구체적인 규칙이 없는 에이전트는 오염을 일으키는 죽은 파일이다.<code>.agents/</code>.</p> <p class="tableblock">=== 단계 6: 모든 프로젝트의 포트폴리오에 프로젝트 추가</p> <p class="tableblock">그것은 우리가 항상 잊어버리는 단계입니다. 각`INDEX.adoc`각 프로젝트는 동일한 방법론으로 모든 프로젝트를 나열하는 '프로젝트 포트폴리오' 테이블을 포함합니다. 새 프로젝트를 생성할 때 반드시 해야 할 일:</p> <p class="tableblock">1. 새 프로젝트 포트폴리오에 라인 추가 (논리) 2. 기존 모든 프로젝트의 포트폴리오에 한 줄 추가하기 — 예, 모두</p> <p class="tableblock">내 네 개(지금은 다섯 개)의 프로젝트에 대해, 이는 여는 것을 의미한다.<code>INDEX.adoc</code> de <code>magic-stick</code>, <code>bakery-gradle</code>, <code>cheroliv.com</code>, `plantuml-gradle`그리고 거기에 줄을 추가`jhipster-gradle-plugins</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Session 1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">…​</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2026-04-28 🆕<code>.</p> <p class="tableblock">이건 지루합니다. 이건 수동적입니다. 이것도 작업 중인 프로젝트가 무엇이든 에이전트가 다른 프로젝트가 무엇인지와 그 상태를 알고 있도록 보장하는 유일한 방법입니다. 세션 012에서`magic-stick</code>, 에이전트는 포트폴리오에서 두 가지 불일치를 감지했습니다 —`bakery-gradle`그의 COMPLETED_TASKS_ARCHIVE가 지연되어 있었고,`plantuml-gradle`_그것은 절차 문서(5단계)와 그 INDEX(6단계)에 차이가 있었다. 이 교차 표가 없었다면, 이러한 불일치는 눈에 띄지 않았을 것이다.</p> <p class="tableblock">[plantuml, format=svg, id=diag-portfolio-graph, alt="Graphe du portefeuille de projets — références croisées entre INDEX.adoc"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam nodeBackgroundColor #E3F2FD</p> <p class="tableblock">title 프로젝트 포트폴리오 — 교차 참조 INDEX.adoc node "<strong>magic-stick</strong> Session 037 SCRIPT_VERIFICATION" as MS #E1BEE7 node "<strong>bakery-gradle</strong> 세션 11 테스트 커버리지" as BG #FFE0B2 node "<strong>cheroliv.com</strong> 세션 10 TEST_COVERAGE" as CH #C8E6C9 node "<strong>plantuml-gradle</strong> 세션 133 테스트 커버리지" as PG #BBDEFB node "<strong>jhipster-gradle</strong> 세션 1 🆕 테스트_커버리지" as JG #FFCDD2</p> <p class="tableblock">MS -→ BG : INDEX.adoc référence MS -→ CH : INDEX.adoc référence MS -→ PG : INDEX.adoc référence MS -→ JG : INDEX.adoc référence 🆕</p> <p class="tableblock">BG -→ MS : INDEX.adoc référence BG -→ CH : INDEX.adoc référence BG -→ PG : INDEX.adoc référence BG -→ JG : INDEX.adoc référence 🆕</p> <p class="tableblock">CH -→ MS : INDEX.adoc référence CH -→ BG : INDEX.adoc référence CH -→ PG : INDEX.adoc référence CH -→ JG : INDEX.adoc référence 🆕</p> <p class="tableblock">PG -→ MS : INDEX.adoc référence PG -→ BG : INDEX.adoc référence PG -→ CH : INDEX.adoc référence PG -→ JG : INDEX.adoc référence 🆕</p> <p class="tableblock">JG -→ MS : INDEX.adoc référence JG -→ BG : INDEX.adoc référence JG -→ CH : INDEX.adoc référence JG -→ PG : INDEX.adoc référence</p> <p class="tableblock">note bottom of JG Quand on ajoute un projet : • 4 INDEX.adoc à mettre à jour • 1 ligne par portefeuille • Coût : 5 minutes end note</p> <p class="tableblock">legend bottom</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">= Couleur</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">= Projet</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><#E1BEE7></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">magic-stick — ISO Linux live</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><#FFE0B2></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">bakery-gradle — Plugin JBake</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><#C8E6C9></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">cheroliv.com — Site personnel</p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><#BBDEFB></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">plantuml-gradle — Plugin IA</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><#FFCDD2></p></td> </tr> </tbody> </table> </div> </div> https://cheroliv.com/blog/2026/0107_jbake_serve_rendering_bug_fix_post.html Wed, 22 Apr 2026 00:00:00 +0000 blog/2026/0107_jbake_serve_rendering_bug_fix_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_장면_네_개의_스크린샷_두_개의_렌더링">장면: 네 개의 스크린샷, 두 개의 렌더링</a> <ul class="sectlevel2"> <li><a href="#_로컬_렌더링">로컬 렌더링</a></li> <li><a href="#_온라인_렌더링">온라인 렌더링</a></li> </ul> </li> <li><a href="#_진단_serve가_올바른_폴더를_가리키고_있지_않았습니다">진단 : `serve`가 올바른 폴더를 가리키고 있지 않았습니다.</a></li> <li><a href="#_근본_원인_jbake_cli는_이렇게_작동하지_않습니다">근본 원인: JBake CLI는 이렇게 작동하지 않습니다</a></li> <li><a href="#_해결책_위치_인자_플래그가_아닌">해결책: 위치 인자, 플래그가 아닌</a></li> <li><a href="#_curl을_사용한_빠른_검증">cURL을 사용한 빠른 검증</a></li> <li><a href="#_왜_이_버그는_교활했는가">왜 이 버그는 교활했는가?</a></li> <li><a href="#_결론">결론</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽기 시간 : 10 minutes</div> <p>로컬에서 사이트가 아무 것도 아닌 것처럼 보였지만, 온라인에 배포된 후에는 모든 것이 깔끔해졌을 때를 아시나요? 이건 내 Gradle JBake 플러그인과 함께 일어났던 일입니다. 작업`serve`네모난 버튼을 표시하고, 검은 배경에 어두운 텍스트를 보여 주었으며, CSS가 이상하게도 빠져 있었습니다. однако`publishSite`같은 사이트를 생성했고, 그것이 완벽했다. 원인은 CSS도, 브라우저도, 캐시도 아니었다. 그것은 Kotlin 코드 한 줄이었고, 명령줄 인수와 관련된 나쁜 습관 때문이었다.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">틱</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_장면_네_개의_스크린샷_두_개의_렌더링">장면: 네 개의 스크린샷, 두 개의 렌더링</h2> <div class="sectionbody"> <div class="paragraph"> <p>시스템 충돌 뒤에 있었다. 나는 로컬 렌더링을 비교하기 위해 스크린샷 네 개를 찍어두었다 (<code>./gradlew serve`위에`localhost:8820</code>) 온라인 렌더링과 함께 (`publishSite`GitHub Pages에서). 페이지당 두 개의 스크린샷 : 위와 아래.</p> </div> <div class="sect2"> <h3 id="_로컬_렌더링">로컬 렌더링</h3> <div class="paragraph"> <p><strong>페이지 상단</strong>— 버튼 <strong>Project</strong> 및 <strong>Template*는<strong>작은, 직사각형</strong>, aux couleurs standards (bleu et vert). La carte *Start Writing</strong> a un<strong>단색 검은 배경</strong>, 틀 없이.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/screen_local1.png" alt="Rendu local - haut de page"> </div> </div> <div class="paragraph"> <p><strong>바닥글</strong>— 부제목 *최신 글과 자료*는<strong>거의 읽을 수 없는</strong>, 검은 배경에 너무 어둡습니다. 블로그 이미지 아래의 날짜('17 October 2013', 등등)은<strong>결석한</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/screen_local2.png" alt="Rendu local - bas de page"> </div> </div> </div> <div class="sect2"> <h3 id="_온라인_렌더링">온라인 렌더링</h3> <div class="paragraph"> <p><strong>페이지 상단</strong>— 같은 버튼들은<strong>큰, 양의, 화려한 네온 초록</strong>, 대문자 텍스트. 카드에는<strong>흰색 둥근 프레임에 그림자</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/screen_online1.png" alt="Rendu en ligne - haut de page"> </div> </div> <div class="paragraph"> <p><strong>하단</strong>— 부제목은<strong>가독성이 좋습니다</strong>. 날짜는<strong>보이는</strong>. 기사 카드에는<strong>둥근 모서리</strong>그리고 제목들은<strong>굵게</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/screen_online2.png" alt="Rendu en ligne - bas de page"> </div> </div> <div class="paragraph"> <p>첫 번째 반사: 테마. 나는 (밝은, 어두운, 높은 대비) 기반의 동적 테마 시스템을 사용`localStorage`. 아마도 로컬 스토어가 고대비 테마를 트리거했을 수도 있지? 아니. 나는 이미 썼어.https://cheroliv.com/blog/2025/0098_preloading_css_variable_post.html[주제 사전 로드에 관한 전체 기사], 나는 어떻게 작동하는지 알아. 그리고 심지어 high-contrast 모드에서도 CSS 구조(타원형 버튼, 그림자)가 있어야 했어. 그런데 그게 없었어.</p> </div> <div class="paragraph"> <p>두 번째 반응: 브라우저 캐시. 아니요, 깨끗한 프로필로 테스트를 했었습니다. diff가 지속되었습니다.</p> </div> <div class="paragraph"> <p>세 번째 반사 :`serve`같은 파일을 제공하지 않았습니다`publishSite`.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_진단_serve가_올바른_폴더를_가리키고_있지_않았습니다">진단 : `serve`가 올바른 폴더를 가리키고 있지 않았습니다.</h2> <div class="sectionbody"> <div class="paragraph"> <p>내 그레이들 플러그인`bakery`두 가지 주요 작업이 있습니다:</p> </div> <div class="ulist"> <ul> <li> <p><code>bake</code>: 안에 정적 사이트를 생성합니다`build/bake/`</p> </li> <li> <p><code>serve</code>: 로컬 웹 서버를 시작합니다</p> </li> <li> <p><code>publishSite</code>: 밀다`build/bake/`GitHub Pages쪽으로</p> </li> </ul> </div> <div class="paragraph"> <p>차이는 오직 …​에서만 나올 수 있었다.<code>serve</code>. Si <code>publishSite`그는 올바른 콘텐츠를 게시하고 있었고, 그것이`build/bake/`좋았어요. 만약`serve`다른 것을 표시하고 있었는데, 그건 그것이役에 서지 못했습니다.`build/bake/</code>.</p> </div> <div class="paragraph"> <p>코드를 봅시다. 안에서`SiteManager.kt`, 작업`serve`다음과 같이 정의됩니다:</p> </div> <div class="listingblock"> <div class="title">SiteManager.kt — La tâche serve (version buggy)</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">tasks.register("serve", JavaExec::class.java) { task -> task.apply { mainClass.set("org.jbake.launcher.Main") classpath = jbakeRuntime environment("GEM_PATH", jbakeRuntime.asPath) jvmArgs(/* ... */) args = listOf( "-b", file(site.bake.srcPath).absolutePath, "-s", layout.buildDirectory.get() .asFile.resolve(site.bake.destDirPath) .absolutePath ) } }</code></pre> </div> </div> <div class="paragraph"> <p><code>org.jbake.launcher.Main`JBake 2.7.0 CLI의 진입점입니다. 아이디어: 전달하다</code>-b`소스 폴더와`-s`대상 폴더에 대해, 서버 모드를 시작합니다. 단, …​</p> </div> </div> </div> <div class="sect1"> <h2 id="_근본_원인_jbake_cli는_이렇게_작동하지_않습니다">근본 원인: JBake CLI는 이렇게 작동하지 않습니다</h2> <div class="sectionbody"> <div class="paragraph"> <p>JBake 2.7.0은(는) 기다리고 있는<strong>위치 인수</strong>소스와 목적지, 그리고 옵션 플래그. 서명은:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">jbake <source> <destination> [options]</code></pre> </div> </div> <div class="paragraph"> <p>그러나 내 코드에서 쓰고 있었는데:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">args = listOf("-b", "/path/to/site", "-s", "/path/to/build/bake")</code></pre> </div> </div> <div class="paragraph"> <p>JBake는 이것을 이렇게 해석했습니다 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><code>-b</code>→ "bake" 플래그(부울)를 파싱, 소비됨</p> </li> <li> <p><code>/path/to/site</code>→ 위치 기반 인수 1이 됩니다 (출처)</p> </li> <li> <p><code>-s</code>→ 'serve' 플래그(불리언)를 파싱, 서버 시작됨<strong>즉시</strong></p> </li> <li> <p><code>/path/to/build/bake</code>→ 버려진 주장이 되어 무시되거나 잘못 해석됩니다.</p> </li> </ol> </div> <div class="paragraph"> <p>결과 : JBake 가져갔다`/path/to/site`소스로서,<strong>목적지를 고려하지 않았습니다.</strong>제공된 (<code>build/bake</code>), 그리고는 기본 디렉터리를 사용하고 있었습니다 (자주`./output`또는 임시 복사본) 파일`css/styles.css`빌드는 덮어쓰여지거나 무시되었고, 그래서 기본 제공되는 오래된 CSS(커스텀 변수도 없고, 둥근 모서리도 없고, 그림자도 없이)가 제공되었습니다.</p> </div> <div class="paragraph"> <p>비교하면,<code>bake</code> et <code>publishSite`그들이 그것을<strong>공식 Gradle JBake 플러그인</strong>(`jbake-gradle-plugin</code>) 깔끔하게 쓰는 안에`build/bake/`Gradle API를 통해. 그들은 CLI를 통과하지 않습니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_해결책_위치_인자_플래그가_아닌">해결책: 위치 인자, 플래그가 아닌</h2> <div class="sectionbody"> <div class="paragraph"> <p>수정은 간단합니다 — 한번 알면 됩니다. 소스와 대상을 위치 인수로 전달하기만 하면 됩니다, 그다음`-s`마지막으로:</p> </div> <div class="listingblock"> <div class="title">SiteManager.kt — La tâche serve (version corrigée)</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">args = listOf( file(site.bake.srcPath).absolutePath, layout.buildDirectory.get() .asFile.resolve(site.bake.destDirPath) .absolutePath, "-s" )</code></pre> </div> </div> <div class="paragraph"> <p>그게 다예요. 세 줄이 변경되었고 버그가 해결되었습니다.</p> </div> <div class="paragraph"> <p>로컬에서 플러그인을 게시한 후 (<code>publishToMavenLocal</code>), un `./gradlew serve`JBake를 올바른 구문으로 실행합니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">jbake /home/user/project/site /home/user/project/build/bake -s</code></pre> </div> </div> <div class="paragraph"> <p>그리고 이번엔, JBake에 내장된 Jetty 서버가 콘텐츠를 잘 제공합니다`build/bake/`— 온라인에 게시된 내용과 동일합니다.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml !define RECTANGLE class package "이전 (버그)" { RECTANGLE JBakeCLI1 { + args = ["-b", "사이트", "-s", "빌드/베이크"] } RECTANGLE Source1 { + site/ } RECTANGLE Dest1 { + ??? (dossier temporaire) } RECTANGLE Jetty1 { + sert mauvais fichiers } JBakeCLI1 --> Source1 : lit JBakeCLI1 -[#red]x Dest1 : destination ignorée Jetty1 --> Dest1 : sert } package "후 (수정)" { RECTANGLE JBakeCLI2 { + args = ["사이트", "빌드/베이크", "-s"] } RECTANGLE Source2 { + site/ } RECTANGLE Dest2 { + build/bake/ } RECTANGLE Jetty2 { + sert les bons fichiers } JBakeCLI2 --> Source2 : lit JBakeCLI2 --> Dest2 : écrit dans Jetty2 --> Dest2 : sert OK } @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_curl을_사용한_빠른_검증">cURL을 사용한 빠른 검증</h2> <div class="sectionbody"> <div class="paragraph"> <p>서버가 올바른 콘텐츠를 제공하고 있는지 확인하기 위해, 간단한`curl`확인한다`index.html`포함한다`data-bs-theme="light"`그리고`build/bake/css/styles.css`정확히 31 402 바이트입니다 — 생성된 파일과 동일한`bake`.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew serve # Dans un autre terminal : $ curl -s http://localhost:8820/ | grep data-bs-theme <html ... data-bs-theme="light" ...> $ curl -I http://localhost:8820/css/styles.css HTTP/1.1 200 OK Content-Length: 31402 Content-Type: text/css</code></pre> </div> </div> <div class="paragraph"> <p>로컬 렌더링은 이제<strong>픽셀-동일</strong>배포된 렌더링에서</p> </div> </div> </div> <div class="sect1"> <h2 id="_왜_이_버그는_교활했는가">왜 이 버그는 교활했는가?</h2> <div class="sectionbody"> <div class="paragraph"> <p>왜 잡기 어려웠는지 보이시죠?</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>명시적 오류 없음</strong>: JBake는 크래시되지 않았습니다. 그것은 단지 잘못된 폴더와 함께 '작동’하고 있었습니다.</p> </li> <li> <p><strong>빌드가 작동하고 있었습니다</strong>:`./gradlew bake`파일을 올바르게 생성하고 있었습니다`build/bake/`.</p> </li> <li> <p><strong>배포가 작동하고 있었다</strong>(Empty)`publishSite`좋은 콘텐츠를 온라인에 게시하고 있었습니다.</p> </li> <li> <p><strong>serve`만 고장 났습니다</strong>: 개발 작업, 그것을 반복하기 위해 계속 사용하는 것.</p> </li> <li> <p><strong>-key value`의 습관</strong>: 개발자로서, 우리는 수년간의 Unix CLI에 익숙해져 있다`-o output`, <code>-i input</code>). JBake CLI는 예외입니다 — 소스와 목적은 위치 기반.</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_결론">결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>JBake를 래핑하는 Gradle 플러그인(또는 기타 CLI 도구 포함)을 유지 관리하는 경우,<strong>인수 문서를 읽으세요</strong>당신이 그들을 알고 있다고 생각하더라도. 암묵적인 가설 (<code>-s</code>= "set destination") 시각적 디버깅에 몇 시간을 소비하게 만들 수 있습니다.</p> </div> <div class="paragraph"> <p>여기서 수정은 말 그대로 변경하는 것이었습니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">args = listOf("-b", src, "-s", dest) // ❌ BUG</code></pre> </div> </div> <div class="paragraph"> <p>en :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">args = listOf(src, dest, "-s") // ✅ FIX</code></pre> </div> </div> <div class="paragraph"> <p>세 개의 토큰이 이동된 후, 내 로컬 사이트는 다시 프로덕션 사이트만큼 아름답게 되었다.</p> </div> <div class="paragraph"> <p><strong>수업</strong>: 로컬과 프로덕션 간 렌더링이 명백한 이유 없이 다를 때, 먼저 *pipeline*을 의심하세요 — CSS가 아니고, 브라우저가 아니고, 더더욱 프레임워크가 아닙니다. 종종 렌더링 직전의 단계가 속이는 경우가 많습니다.</p> </div> </div> </div> https://cheroliv.com/blog/2026/0106_opencode_path_sdkman_nvm_post.html Tue, 21 Apr 2026 00:00:00 +0000 blog/2026/0106_opencode_path_sdkman_nvm_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_장면_도구의_세계에서_눈먼_에이전트">장면: 도구의 세계에서 눈먼 에이전트</a></li> <li><a href="#_버그의_해부_두_개의_쉘_두_개의_세계">버그의 해부 : 두 개의 쉘, 두 개의 세계</a></li> <li><a href="#_범인들_zshrc_vs_zshenv">범인들: <code>.zshrc</code> vs `.zshenv</a></li> <li><a href="#_단계별_진단">단계별 진단</a> <ul class="sectlevel2"> <li><a href="#_1_에이전트_path_확인">1. 에이전트 PATH 확인</a></li> <li><a href="#_2_zshrc에_있지만_zshenv에_없는_것을_식별한다">2. .zshrc에 있지만 .zshenv에 없는 것을 식별한다</a></li> <li><a href="#_3_zshenv_파일이_존재하는지_확인">3. .zshenv 파일이 존재하는지 확인</a></li> </ul> </li> <li><a href="#_해결책_zshenv_올바른_경로">해결책 : .zshenv + 올바른 경로</a> <ul class="sectlevel2"> <li><a href="#_필수적인_모든_경로를_포함한_zshenv_파일을_만드세요">필수적인 모든 경로를 포함한 .zshenv 파일을 만드세요.</a></li> <li><a href="#_왜_zshenv에서_source_sdkman_init_sh를_사용하지_않을까">왜 .zshenv에서 `source sdkman-init.sh`를 사용하지 않을까?</a></li> </ul> </li> <li><a href="#_nvm_케이스_버전_관리자가_흔적을_남기는_것을_잊을_때">NVM 케이스: 버전 관리자가 흔적을 남기는 것을 잊을 때</a> <ul class="sectlevel2"> <li><a href="#_nvm_문제">NVM 문제</a></li> <li><a href="#_해결책_current_심볼릭_링크를_nvm용으로_생성">해결책: <code>current</code> 심볼릭 링크를 NVM용으로 생성</a></li> <li><a href="#_심볼릭_링크_업데이트_자동화">심볼릭 링크 업데이트 자동화</a></li> </ul> </li> <li><a href="#_경로_요약_표">경로 요약 표</a></li> <li><a href="#_함정과_완화">함정과 완화</a></li> <li><a href="#_배운_교훈">배운 교훈</a></li> <li><a href="#_최종_검증">최종 검증</a></li> <li><a href="#_링크">링크</a> <ul class="sectlevel2"> <li><a href="#_공식_문서">공식 문서</a></li> <li><a href="#_언급된_도구">언급된 도구</a></li> <li><a href="#_더_깊이">더 깊이</a></li> </ul> </li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽기 시간 : 13 minutes</div> <p>당신은 터미널에서 OpenCode를 실행하고, 모든 것이 정상적으로 작동합니다. 에이전트는 시도합니다`gh`— 찾을 수 없음. 하나`java -version`— 부재한. 하나`node`— 어디에도 없습니다. 하지만,これらのツール들은 <em>votre</em> shell 안에 분명히 있습니다. 문제는? OpenCode는 셸을 실행합니다.<strong>비상호적</strong>당신의 것을 절대 읽지 않는`.zshrc`. 여기서 진단하고 깔끔하게 수정하는 방법입니다.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">똑</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_장면_도구의_세계에서_눈먼_에이전트">장면: 도구의 세계에서 눈먼 에이전트</h2> <div class="sectionbody"> <div class="paragraph"> <p>그것은 화요일 저녁이었고, 나는 방금 설치하고 있었다.https://opencode.ai[OpenCode], 코딩 방식을 바꿔줄 것을 약속했던 AI 에이전트. 첫 번째 테스트 : 그것을 이용해 나의 GitHub 저장소 목록을 요청하기.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ opencode > Utilise gh pour lister mes repos ❌ bash: gh: command not found</code></pre> </div> </div> <div class="paragraph"> <p>이상하다`gh`내 터미널에서 완벽하게 작동했습니다. 다른 것을 시도해 보고 있습니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">> Vérifie la version de Java ❌ bash: java: command not found</code></pre> </div> </div> <div class="paragraph"> <p>그리고:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">> Lance le build Gradle ❌ bash: gradle: command not found</code></pre> </div> </div> <div class="paragraph"> <p>Java, Gradle, Node,<code>gh</code>— 모든 것이 요원에게 보이지 않았다. 내 터미널은 모든 것을 볼 수 있었다. 요원과 내가 두 개의 평행 세계에 살고 있는 것처럼.</p> </div> <div class="paragraph"> <p>이해하는 데 몇 시간이 걸렸습니다. 몇 시간의`echo $PATH`, de <code>which java</code>, 점점 커지는 불만. 나는 결국 이해했다 — 문제는 도구가 아니었고, 그것이<strong>쉘</strong>. OpenCode은 모든 하위 프로세스를 실행하는 에이전트처럼, 쉘에서 작업합니다.<strong>비대화식</strong>. 그리고 Zsh는 이러한 셸에서 단순히 당신의`.zshrc`.</p> </div> <div class="paragraph"> <p>다음은 진단, 해결 방법, 그리고 제가 배운 교훈에 대한 전체적인 설명입니다. — OpenCode, Aider, Cursor, 또는 cron 스크립트와 같은 AI 에이전트를 사용한다면 언젠가 이 문제에 직면하게 될 것입니다. — 이 문제는 언젠가 당신에게 영향을 미칠 것입니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_버그의_해부_두_개의_쉘_두_개의_세계">버그의 해부 : 두 개의 쉘, 두 개의 세계</h2> <div class="sectionbody"> <div class="paragraph"> <p>터미널을 열면 Zsh는 이를 쉘로 처리합니다.<strong>대화형</strong>. 그의 충전한다`.zshrc`, 이 모든 것을 초기화합니다: SDKMAN, NVM, pnpm, 별칭, 멋진 프롬프트. 환경을 완성했습니다.</p> </div> <div class="paragraph"> <p>하지만 OpenCode가 명령을 실행할 때, 대화형 터미널을 실행하지 않습니다. 셸을 실행합니다.<strong>비대화형</strong>— 작업 셸, 화면 뒤에 인간이 없는. 그리고 Zsh는 이 상황에서 점프한다.<code>.zshrc</code>. 그는 다만 읽는다.<code>.zshenv</code>.</p> </div> <div class="paragraph"> <p>왜 이 구분이 존재하는가? 왜냐하면 비대화형 셸은 스크립트를 실행하도록 설계되었고, 인간 사용자를 위해 설계된 것이 아니기 때문이다. 백그라운드에서 실행되는 스크립트에 별칭, 프롬프트, 자동완성을 로드하는 것은 낭비이다. 문제는, 실행 가능한 파일을 찾는 데 가장 중요한 정보인 사용자의 PATH가 자주 초기화되는 곳에`.zshrc`, 안에 있지 않아`.zshenv`.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE actor "당신" as user actor "OpenCode (에이전트)" as agent participant "셸 대화형 (.zshrc 소스된)" as ishell participant "Shell 비대화형 (.zshrc 무시됨)" as nshell user -> ishell : gh, java, node ✅ agent -> nshell : gh, java, node ❌ note right of ishell Source .zshrc : - SDKMAN init - NVM init - ~/apps dans PATH - pnpm dans PATH end note note right of nshell .zshrc ignoré ! PATH = /usr/bin:/bin + quelques répertoires défaut end note @enduml</pre> </div> </div> <div class="paragraph"> <p>문제의 근원 :<strong>Zsh는 대화형 셸에서만 <code>.zshrc`를 소스합니다</strong>. OpenCode, 모든 IA 에이전트가 서브프로세스를 시작할 때와 마찬가지로, 비대화형 셸을 사용합니다. 이 셸은 오직 읽습니다.</code>.zshenv`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_범인들_zshrc_vs_zshenv">범인들: <code>.zshrc</code> vs `.zshenv</h2> <div class="sectionbody"> <div class="paragraph"> <p>Zsh는 가지고 있습니다<strong>네 개의 초기화 파일</strong>, 각kak 특정 역활을 가진. 세련된 디자인이다 — 이것도 문제의 핵심:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">파일</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">소싱된 때</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">역할</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">PATH를 수정해?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.zshenv</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>항상</strong>(대화형 + 비대화형 + 로그인)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">필수 환경 변수, PATH</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ 예 — 이것이 SA의 자리다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.zprofile</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">로그인 셸만</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">느린 명령어 (세션당 한 번)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">가능한</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.zshrc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>대화형 쉘만</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">별명, 프롬프트, 자동 완성, 대화형 도구</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌ 중요한 변수에는 사용하지 마세요</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.zlogin</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">로그인 셸(.zshrc 이후)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">환영 메시지, 완료</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">드물게</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>표는 힌트를 주지만, 깊이 이해해야 합니다. 집의 방처럼 생각해 보세요:</p> </div> <div class="ulist"> <ul> <li> <p>`.zshenv`은/는<strong>로비</strong>— 모두가 여기서 지나갑니다, 방문자든 거주자든. 여기에 무언가를 놓으면, 모든 셸이 이를 볼 수 있습니다.</p> </li> <li> <p>`.zshrc`은/는<strong>거실</strong>— 단지 주민(대화형 셸)만 들어갑니다. 방문자(비대화형 셸)는 로비에 머무릅니다.</p> </li> <li> <p><code>.zprofile</code> et `.zlogin`로그인 셸을 위한 특수 구성 요소이며 (SSH로 연결할 때처럼).</p> </li> </ul> </div> <div class="paragraph"> <p>비극은 우리 대부분이 PATH를 거실에 두는 것이라는 점이다. 그리고 AI 에이전트는 거실에 들어갈 수 없다.</p> </div> <div class="paragraph"> <p>문제를 다이어그램으로 표현하면 :</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE start if (Shell interactif ?) then (Oui) :Source .zshenv; :Source .zprofile; :Source .zshrc; :Source .zlogin; note right SDKMAN ✅ NVM ✅ ~/apps ✅ pnpm ✅ end note else (Non — shell non-interactif) :Source .zshenv uniquement; note right SDKMAN ❌ NVM ❌ ~/apps ❌ pnpm ❌ end note endif stop @enduml</pre> </div> </div> <div class="paragraph"> <p>터미널을 열면, Zsh는 대화형입니다: 읽습니다`.zshrc`, 모든 것이 작동합니다. OpenCode가 셸을 실행하여 명령을 실행할 때, Zsh는 비대화형입니다:それは 건너뜁니다.<code>.zshrc</code>, 읽기만`.zshenv`. Et si `.zshenv`존재하지 않거나 PATH를 포함하지 않습니다 — 이것이 황무지입니다.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>왜 Zsh가 그렇게 하는가?</strong>이것은 Unix에서 상속받은 설계 선택이다. 비대화형 쉘이어야 한다<strong>빠른</strong> et <strong>재현 가능한</strong>. 별칭, 색이 있는 프롬프트, SDKMAN의 무거운 초기화를 크론 스크립트나 AI 에이전트에 로드하면 느리고 취약할 것입니다. 따라서 분리는 논리적 :`.zshenv`principalement (변수, PATH),`.zshrc`편안함을 위해 (aliases, prompt, complétons). 문제는 핵심 을 편안함에 두면 발생한다.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_단계별_진단">단계별 진단</h2> <div class="sectionbody"> <div class="paragraph"> <p>수정하기 전에 정확히 무엇이 부족한지 이해해야 합니다. 다음은 재현 가능한 진단 방법입니다 — AI 에이전트와 작업한다면 즐겨찾기에 저장하세요.</p> </div> <div class="sect2"> <h3 id="_1_에이전트_path_확인">1. 에이전트 PATH 확인</h3> <div class="paragraph"> <p>대화형 터미널이 보는 내용과 비대화형 셸이 보는 내용을 비교합니다 — 즉, OpenCode가 보는 내용입니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Dans votre terminal interactif (tout fonctionne) echo $PATH | tr ':' '\n' | grep -v '^/usr' | sort</code></pre> </div> </div> <div class="paragraph"> <p>일반적인 결과 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">/home/cheroliv/apps /home/cheroliv/.nvm/versions/node/v22.19.0/bin /home/cheroliv/.sdkman/candidates/java/current/bin /home/cheroliv/.sdkman/candidates/gradle/current/bin /home/cheroliv/.local/share/pnpm /home/cheroliv/.local/bin</code></pre> </div> </div> <div class="paragraph"> <p>이제 에이전트가 보는 것을 시뮬레이션해 봅시다 — 비대화형 셸 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Shell non-interactif : pas de .zshrc zsh -c 'echo $PATH' | tr ':' '\n' | grep -v '^/usr' | sort</code></pre> </div> </div> <div class="paragraph"> <p>결과 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">/home/cheroliv/.local/bin</code></pre> </div> </div> <div class="paragraph"> <p><strong>여섯 길 중 다섯이 사라졌다.</strong>에이전트는 환경의 83%를 잃었습니다. 마치 당신이 절반의 조리 도구 없이 요리하라고 요청받은 것과 같습니다 — 물을 끓일 수는 있지만, 그 외에는 거의 할 수 있는 게 없습니다.</p> </div> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td> <td class="content"> <div class="paragraph"> <p>명령`zsh -c 'echo $PATH'`당신의<strong>1등 진단 도구</strong>. 매일 사용하는 도구가 결과에 포함되지 않으면, AI 에이전트도 그것을 볼 수 없습니다. 수정 전과 후에 테스트해 보세요. de`.zshenv`.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_2_zshrc에_있지만_zshenv에_없는_것을_식별한다">2. .zshrc에 있지만 .zshenv에 없는 것을 식별한다</h3> <div class="paragraph"> <p>이제, 우리는 범인을 찾고 있는 에서`.zshrc`. 우리는 우리 도구를 언급하는 줄을 필터링합니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">grep -n 'apps\|SDKMAN\|NVM\|PNPM\|PATH' ~/.zshrc</code></pre> </div> </div> <div class="paragraph"> <p>일반적으로 발견됩니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">119: PATH="/usr/bin/python3:$HOME/apps:$PATH" # ← pas exporté ! 171: export NVM_DIR="$HOME/.nvm" 172: [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # ← NVM init 176: nvm use --lts --silent # ← active une version 179: export PNPM_HOME="/home/cheroliv/.local/share/pnpm" 187: export SDKMAN_DIR="$HOME/.sdkman" 188: [[ -s "$HOME/.sdkman/bin/sdkman-init.sh" ]] && source "$HOME/.sdkman/bin/sdkman-init.sh"</code></pre> </div> </div> <div class="paragraph"> <p>그 모든 것이<strong>보이지 않는</strong>OpenCode를 위해. 그리고 그`PATH`119번째 줄조차도 아닌`export`é — 현재 셸을 절대 떠나지 않습니다. 이것은 중요한 기술적 세부 사항입니다: 변수 없이`export`이 변수는 해당 셸에 국소적이다. 서브셸 — OpenCode에 의해 시작된 것들처럼 — 은 이를 결코 상속받지 않는다.</p> </div> </div> <div class="sect2"> <h3 id="_3_zshenv_파일이_존재하는지_확인">3. .zshenv 파일이 존재하는지 확인</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">cat ~/.zshenv 2>/dev/null || echo "FICHIER ABSENT"</code></pre> </div> </div> <div class="paragraph"> <p>답변이 « FICHIER ABSENT »이면, 여기서 모든 것이 결정된다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_해결책_zshenv_올바른_경로">해결책 : .zshenv + 올바른 경로</h2> <div class="sectionbody"> <div class="paragraph"> <p>전략은 간단하지만 정밀함이 필요합니다: 안에 넣기`.zshenv` <strong>오직</strong>필수 경로는, 무거운 초기화 스크립트를 소싱하지 않고. 우리는 이동하지 않습니다`.zshrc`안에`.zshenv`— 핵심 내용을 추출합니다.</p> </div> <div class="sect2"> <h3 id="_필수적인_모든_경로를_포함한_zshenv_파일을_만드세요">필수적인 모든 경로를 포함한 .zshenv 파일을 만드세요.</h3> <div class="paragraph"> <p>`.zshenv`은/는<strong>단일 파일</strong>Zsh가 소스를 보장하는<strong>모두</strong>문맥들. PATH가 가야 할 곳은 여기입니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">export SDKMAN_DIR="$HOME/.sdkman" export NVM_DIR="$HOME/.nvm" export PNPM_HOME="$HOME/.local/share/pnpm" export PATH="$HOME/apps:$HOME/.sdkman/candidates/java/current/bin:$HOME/.sdkman/candidates/gradle/current/bin:$HOME/.nvm/current/bin:$PNPM_HOME:$HOME/.local/bin:$HOME/.local/share/JetBrains/Toolbox/scripts:/usr/bin/python3:$PATH"</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>사용합니다`$HOME/.nvm/current/bin`그리고 안`$HOME/.nvm/versions/node/v22.19.0/bin`. 이유 : Node 버전이 변경됩니다. 고정된 경로가 다음에 잘못됩니다.<code>nvm install</code>. 다음 섹션에서 더 자세한 정보를 확인할 수 있습니다.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_왜_zshenv에서_source_sdkman_init_sh를_사용하지_않을까">왜 .zshenv에서 `source sdkman-init.sh`를 사용하지 않을까?</h3> <div class="paragraph"> <p>가장 유혹적인 접근법은 단순히 그곳에 재현하는 것이다`.zshenv`우리가 하는 것 안에`.zshrc`— 초기화 스크립트를 소스로 실행하다. 우리는<strong>할 수 있을</strong>하고 싶은 유혹이 있다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># ❌ MAUVAISE IDÉE [[ -s "$HOME/.sdkman/bin/sdkman-init.sh" ]] && source "$HOME/.sdkman/bin/sdkman-init.sh"</code></pre> </div> </div> <div class="paragraph"> <p>문제 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>느린</strong>:`sdkman-init.sh`각 셸마다 네트워크 해결 및 검사를 수행합니다. 비대화형 셸에서는 이는 불필요한 비용입니다.</p> </li> <li> <p><strong>취약한</strong>: SDKMAN은 대화형 환경을 기대합니다. 초기화가 파이프 또는 서브셸에서 조용히 실패할 수 있습니다.</p> </li> <li> <p><strong>쓸모없는</strong>: SDKMAN은 후보자들을`~/.sdkman/candidates/<tool>/current/bin`— 안정적인 심볼릭 링크가 활성 버전을 가리키고 있습니다. 이를 사용할 수 있습니다.<strong>직접</strong>.</p> </li> </ul> </div> <div class="paragraph"> <p>올바른 접근 방식: SDKMAN 초기화를 우회하고 심볼릭 링크를 직접 가리키기`current`. 이것은 전체 해결책의 열쇠 :<strong>파일 구조를 계약으로 사용하고, 초기화 코드 대신 사용하라</strong>.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE rectangle "느린 접근 (source sdkman-init.sh)" as slow { card ".zshenv에서 sdkman-init.sh 소스 쉘당 2-3초 네트워크 점검 실패 위험" as s1 #FDEDEC } rectangle "빠른 접근 (직접 심볼릭 링크)" as fast { card ".zshenv export PATH=...current/bin\n0 ms\nPas de réseau\nPas d'initialisation" as s2 #E8F8E8 } slow --> fast : Même résultat final\nLe PATH pointe sur current/bin\ndans les deux cas @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_nvm_케이스_버전_관리자가_흔적을_남기는_것을_잊을_때">NVM 케이스: 버전 관리자가 흔적을 남기는 것을 잊을 때</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_nvm_문제">NVM 문제</h3> <div class="paragraph"> <p>이곳이 조사가 나를 가장 멀리 이끌어간 곳입니다. SDKMAN은 세련된 디자인을 가지고 있습니다: 당신이 할 때`sdk install java 25.0.2-tem`, 심볼릭 링크를 생성합니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">~/.sdkman/candidates/java/current -> ~/.sdkman/candidates/java/25.0.2-tem</code></pre> </div> </div> <div class="paragraph"> <p>이 심볼릭 링크는<strong>항상 최신</strong>. 이 안에 가리키세요`.zshenv`그리고 당신은 보호받고, 어떤 셸이든 상관 없습니다. Beautiful.</p> </div> <div class="paragraph"> <p>신경 쓰지 마, 그는 만들지 않아<strong>아무것도</strong>텔의. 심볼릭 링크 없음`current`. 안정된 앵커 포인트가 없습니다. 우리는 하드코딩된 버전된 경로를 가리켜야 하며, 그것은 다음과 같이 보입니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">~/.nvm/versions/node/v22.19.0/bin/node</code></pre> </div> </div> <div class="paragraph"> <p>다음에`nvm install 24`, 이 길은 죽었습니다. 당신의`.zshenv`더 이상 활성 버전이 아닌 버전을 가리키게 됩니다. 이것은 시한 폭탄입니다.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>NVM은 왜 그렇게 하는가?</strong>NVM은 PATH를 동적으로 수정하여 매번`nvm use`. 이는 버전을 자주 바꾸는 개발자를 위해 설계되었으며, 대화형 셸에서 사용됩니다. 심볼릭 링크`current`처음 사양에 들어 있지 않았습니다 — 이것은 우리가 직접 수정할 설계상의 실수입니다.</p> </div> </td> </tr> </table> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE package "SDKMAN ✅" { [~/.sdkman/candidates/java/current] as sdk_current [~/.sdkman/candidates/java/25.0.2-tem/] as java_25 [~/.sdkman/candidates/java/21.0.7-tem/] as java_21 sdk_current --> java_25 : symlink } package "NVM ❌ (수정 전)" as nvm_before { [~/.nvm/versions/node/v22.19.0/] as node_22 [~/.nvm/versions/node/v20.16.0/] as node_20 note right of node_22 Pas de symlink current ! .zshenv doit pointer en dur Cassé au prochain nvm install end note } package "NVM ✅ (수정 후)" as nvm_after { [~/.nvm/current] as nvm_current [~/.nvm/versions/node/v22.19.0/] as node_22b [~/.nvm/versions/node/v20.16.0/] as node_20b nvm_current --> node_22b : symlink\n(mis à jour auto) } @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_해결책_current_심볼릭_링크를_nvm용으로_생성">해결책: <code>current</code> 심볼릭 링크를 NVM용으로 생성</h3> <div class="paragraph"> <p>NVM이 그것을 하지 않기 때문에, 우리가 직접 합니다. 원리는 SDKMAN과 동일합니다 — 심볼릭 링크`current`항상 활성 버전을 가리키는. 한 번 생성한 후 자동화하여 스스로 업데이트되도록 합니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Créer le symlink initial ln -sfn "$HOME/.nvm/versions/node/v22.19.0" "$HOME/.nvm/current"</code></pre> </div> </div> <div class="paragraph"> <p>지금, 안에서`.zshenv`, 사용합니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$HOME/.nvm/current/bin</code></pre> </div> </div> <div class="paragraph"> <p>대신에:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># ❌ Chemin en dur — cassé au prochain changement de version $HOME/.nvm/versions/node/v22.19.0/bin</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_심볼릭_링크_업데이트_자동화">심볼릭 링크 업데이트 자동화</h3> <div class="paragraph"> <p>심볼릭 링크는 갱신되지 않으면 쓸모가 없다. 심볼릭 링크`current`업데이트해야 할 때`nvm use` ou <code>nvm install</code>. 해결책 : 하나<strong>래퍼</strong>— 진짜 명령을 감싸는 함수`nvm`그리고 각 호출 후에 심볼릭 링크를 업데이트합니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># À la fin de .zshrc, APRÈS le chargement de NVM nvm use --lts --silent ln -sfn "$(nvm_version_path "$(nvm current)")" "$NVM_DIR/current" _nvm() { command nvm "$@" local rc=$? ln -sfn "$(nvm_version_path "$(nvm current)")" "$NVM_DIR/current" return $rc } alias nvm='_nvm'</code></pre> </div> </div> <div class="paragraph"> <p>작동 방식, 자세히 :</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE actor Développeur participant "nvm 래퍼\n(_nvm)" as wrapper participant "nvm 실제 (command nvm)" as realnvm participant "~/.nvm/current\n(심볼릭 링크)" as symlink Développeur -> wrapper : nvm use 20 wrapper -> realnvm : command nvm use 20 realnvm --> wrapper : version activée wrapper -> symlink : ln -sfn .../v20.16.0 ~/.nvm/current wrapper --> Développeur : retour note right of symlink Toujours à jour ! Utilisé par .zshenv → accessible par OpenCode end note @enduml</pre> </div> </div> <div class="paragraph"> <p>래퍼`_nvm`실제 명령을 호출한다`nvm`, 그리고 심볼릭 링크를 업데이트합니다. 별칭`nvm='_nvm'`입력할 때 그렇게 되도록`nvm`, 우리는 래퍼를 통해 진행합니다. 그리고 셸 초기화 시에도 동일한 작업을 수행합니다.<code>nvm use --lts</code>.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p>`nvm_version_path`는 NVM의 내부 기능으로, 버전의 전체 경로를 해결합니다. 이로 인해 경로를 수동으로 다시 구성할 필요가 없습니다.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_경로_요약_표">경로 요약 표</h2> <div class="sectionbody"> <div class="paragraph"> <p>트랩으로 넘어가기 전에, 변환의 시각적 요약. 좌측에, 당신이 가졌던 (모든 것`.zshrc`, 에이전트에게 보이지 않음). 오른쪽에서, 당신이 지금 가지고 있는 것 (필수 경로 내`.zshenv`, 모든 곳에 보이는).</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">도구</th> <th class="tableblock halign-left valign-top">이전 (.zshrc만)</th> <th class="tableblock halign-left valign-top">이후에 (.zshenv + symlink)</th> <th class="tableblock halign-left valign-top">OpenCode에서 보이는가?</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>~/apps</code>(gh, vscode)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">PATH가 .zshrc에서 내보내지지 않음</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>$HOME/apps</code>.zshenv 안에</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">SDKMAN 자바</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>sdkman-init.sh</code>.zshrc에서 소스됨</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>$HOME/.sdkman/candidates/java/current/bin</code>.zshenv 안에</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">SDKMAN 그레이들</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>sdkman-init.sh</code>.zshrc에서 소스됨</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>$HOME/.sdkman/candidates/gradle/current/bin</code>.zshenv 안에</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">NVM 노드</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>nvm use --lts</code>.zshrc 안에</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>$HOME/.nvm/current/bin</code>.zshenv (심볼릭 링크) 안에</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">pnpm</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>$PNPM_HOME</code>.zshrc 안에</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>$PNPM_HOME</code>.zshenv 안</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">JetBrains Toolbox</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Toolbox에 의해 `.zshrc`에 자동으로 추가됨</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>$HOME/.local/share/JetBrains/Toolbox/scripts</code>.zshenv 안에</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">파이썬 3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`/usr/bin/python3`PATH .zshrc 안에</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">.zshenv에서 명시적으로</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_함정과_완화">함정과 완화</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 접근 방식에서는 모든 것이 완벽하지 않습니다. 제가 겪은 문제점과 이를 우회하는 방법을 소개합니다.</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">함정</th> <th class="tableblock halign-left valign-top">설명</th> <th class="tableblock halign-left valign-top">완화</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">중복된 PATH</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">.zshenv과 .zshrc가 동일한 경로를 추가하면, 그 경로가 두 번 나타납니다</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`.zshenv`소싱되었습니다<strong>이전</strong>.zshrc. 두 파일이 대화형 셸에서 읽힙니다. PATH가 중복될 수 있습니다. 이것은 미적인 문제일 뿐 기능적인 문제는 아닙니다. 이를 방지하려면 .zshenv에 기본 PATH에 없는 <em>absents</em> 경로만 넣으세요.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">NVM: .zshenv에 하드코딩된 버전</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">놓다`~/.nvm/versions/node/v22.19.0/bin`콘크리트에서 다음에 거짓이 된다`nvm install`</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">심볼릭 링크 사용`$HOME/.nvm/current/bin`+ 래퍼`_nvm`안 .zshrc</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">SDKMAN : .zshenv에서 sdkman-init.sh 소스하기</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">느리고, 취약하며, 비대화형 쉘에서는 쓸모가 없습니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">심볼릭 링크 사용`candidates/<tool>/current/bin`직접적으로</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">수정 후 누락된 별칭</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">래퍼`nvm='_nvm'`.zshrc에서 는 다시 로드한 후에만 적용됩니다</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">쉘을 다시 시작하거나`source ~/.zshrc`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">OpenCode는 변경사항을 보지 않는다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">에이전트는 이미 기존 .zshenv을 사용해 하위 셸을 실행했습니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">OpenCode 수정한 .zshenv 후 다시 시작</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">.zshenv이 과도하게 로드됨</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">무거운 함수나 대화형 초기화를 .zshenv에 넣으세요.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">.zshenv = 환경 변수 + PATH만. 없습니다`source`, 무거운 함수 없음, 프롬프트 없음.</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_배운_교훈">배운 교훈</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>.zshrc`는 대화형입니다, <code>.zshenv`은 범용입니다</strong>— 변수가 <em>모든</em> 셸(에이전트 AI, cron, 스크립트, IDE)에 존재해야 한다면, 그것은</code>.zshenv`. 거실은 편안하지만, 입구 홀은 모두가 지나가는 유일한 장소입니다.</p> </li> <li> <p><strong>버전 관리자들은 동일하지 않다.</strong>— SDKMAN은 심볼릭 링크를 생성합니다.`current`설계상. NVM 아니오. 이 부족함을 수동으로 채워야 합니다. 이것은 중요한 교훈입니다: PATH를 설정하기 전에, 관리자가 안정적인 고정점을 제공하는지 확인하세요.</p> </li> <li> <p><strong>.zshenv에서 init 스크립트를 소스하지 마세요</strong> — <code>sdkman-init.sh</code> et `nvm.sh`대화형 셸을 위해 설계되었습니다. 비대화형 컨텍스트에서는 느리고 취약합니다. 심볼릭 링크`current`그들은 충분하고 즉각적이다.</p> </li> <li> <p><strong>비대화형 쉘에서 항상 테스트</strong>—`zsh -c 'echo $PATH'`에이전트가 보는 것을 정확히 시뮬레이션합니다. 이것은 검증 테스트입니다. 이 테스트가 없으면, 에이전트에 대해 구성이 작동하는지 알 수 없습니다.</p> </li> <li> <p><strong>래퍼 패턴은 재사용 가능합니다.</strong>— 같은 패턴`_nvm`+`alias nvm='_nvm'`모든 PATH를 동적으로 수정하지만 흔적을 남기지 않는 도구에 적용됩니다. 이것은 당신의 아이디어 상자에 하나 더 추가되는 도구입니다.</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE rectangle "전에" as avant { card "대화형 셸 : ✅ 비대화형 셸 : ❌ OpenCode : ❌ Cron : ❌ 스크립트 : ❌" as av1 #FDEDEC } rectangle "후에" as apres { card "대화형 셸 : ✅\n비대화형 셸 : ✅\nOpenCode : ✅\nCron : ✅\nScripts : ✅" as ap1 #E8F8E8 } avant --> apres : .zshenv +\nsymlink ~/.nvm/current @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_최종_검증">최종 검증</h2> <div class="sectionbody"> <div class="paragraph"> <p>생성한 후`.zshenv`그리고 NVM 심볼릭 링크, 모든 것이 작동하는지 확인하세요 — 두 가지 컨텍스트 모두에서 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Shell interactif (votre terminal) gh --version && java -version && node --version</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Shell non-interactif (simulation OpenCode) zsh -c 'gh --version && java -version && node --version'</code></pre> </div> </div> <div class="paragraph"> <p>둘 다 성공해야 합니다. 그렇게 된다면, 귀하의 IA 에이전트가 귀하와 동일한 도구를 볼 것입니다. 그렇지 않다면, 단계별 진단으로 돌아가세요 — 아마도 경로를 잊었거나 NVM 심링크가 최신이 아닐 것입니다.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>이 테스트를 자동화하세요.</strong>이 검사를 도구 업데이트 후에 실행하는 healthcheck 스크립트에 추가하세요. 하나`zsh -c 'which java && which node && which gh'`CI에서는 예상치 못한 상황에 대비하는 보험입니다.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p><em><em>_ 대화형이 아닌 셸은 침묵하는 손님과 같다: 그것은 입구에 표시된 것만 읽는다. PATH가 거실에 있으면, 그것을 결코 볼 수 없다. </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_링크">링크</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_공식_문서">공식 문서</h3> <div class="ulist"> <ul> <li> <p><a href="https://zsh.sourceforge.io/Doc/Release/Files.html">Zsh 문서 : 시작 파일</a>— Zsh 초기화 파일에 대한 공식 참조입니다. 여기가 모든 것이 설명되는 곳이지만, 종종 잊혀지기도 합니다.</p> </li> <li> <p><a href="https://opencode.ai/docs/config/">OpenCode : 구성</a>— OpenCode 및 실행 환경 설정 방법.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_언급된_도구">언급된 도구</h3> <div class="ulist"> <ul> <li> <p><a href="https://github.com/nvm-sh/nvm">GitHub의 NVM</a>— Node Version Manager. Node.js 버전 관리자.</p> </li> <li> <p><a href="https://sdkman.io">SDKMAN — 공식 사이트</a>— SDKMAN! JVM(Java, Kotlin, Gradle 등)의 버전 관리자</p> </li> <li> <p><a href="https://sdkman.io/install">SDKMAN: 설치</a>— SDKMAN 설치 가이드.</p> </li> <li> <p><a href="https://cli.github.com">gh` — 깃허브 CLI</a>— GitHub 커맨드라인 도구, 모든 개발자에게 필수적인</p> </li> <li> <p><a href="https://gradle.org">Gradle — 공식 사이트</a>— SDKMAN을 통해 설치하는 빌드 시스템.</p> </li> <li> <p><a href="https://pnpm.io">pnpm — 공식 사이트</a>— 빠르고 공간을 절약하는 Node.js 패키지 관리자.</p> </li> <li> <p><a href="https://www.jetbrains.com/toolbox-app/">JetBrains 툴박스</a>— JetBrains IDE 관리자, PATH에 스크립트를 추가합니다.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_더_깊이">더 깊이</h3> <div class="ulist"> <ul> <li> <p><a href="https://blog.andy2003.org/posts/2022/zsh-dotfiles/">Zsh dotfiles : 완전한 가이드</a>Zsh dotfiles 관리에 대한 심도 있는 기사</p> </li> <li> <p><a href="https://wiki.archlinux.org/title/Zsh">ArchWiki에서 Zsh</a>— Zsh에 대한 최고의 커뮤니티 문서 중 하나.</p> </li> <li> <p><a href="https://github.com/nvm-sh/nvm/issues">NVM 이슈 GitHub</a>— 심볼릭 링크 주변의 토론을 보려면`current`그리고 PATH 문제를 포함합니다.</p> </li> </ul> </div> </div> </div> </div> https://cheroliv.com/blog/pilot-batch/0105_integrer_graphify_workflow_gradle_post.html Sun, 19 Apr 2026 00:00:00 +0000 blog/pilot-batch/0105_integrer_graphify_workflow_gradle_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_문제_항상_코드보다_뒤처진_다이어그램">문제: 항상 코드보다 뒤처진 다이어그램</a></li> <li><a href="#_해결책_결정적_파이프라인_knowledge_graph_plantuml">해결책: 결정적 파이프라인 Knowledge Graph → PlantUML</a></li> <li><a href="#_단계_1_graphify_설치_및_knowledge_graph_추출">단계 1 : Graphify 설치 및 Knowledge Graph 추출</a> <ul class="sectlevel2"> <li><a href="#_설치">설치</a></li> <li><a href="#_제외_항목_구성">제외 항목 구성</a></li> <li><a href="#_지식_그래프_추출">지식 그래프 추출</a></li> </ul> </li> <li><a href="#_단계_2_gradle_플러그인이_knowledge_graph를_plantuml로_변환합니다">단계 2 : Gradle 플러그인이 Knowledge Graph를 PlantUML로 변환합니다.</a> <ul class="sectlevel2"> <li><a href="#_파이프라인_아키텍처">파이프라인 아키텍처</a></li> <li><a href="#_내부_구성_요소">내부 구성 요소</a></li> <li><a href="#_렌더링_규칙">렌더링 규칙</a></li> </ul> </li> <li><a href="#_3단계_일상_사용">3단계: 일상 사용</a> <ul class="sectlevel2"> <li><a href="#_완전한_다이어그램">완전한 다이어그램</a></li> <li><a href="#_커뮤니티별_필터">커뮤니티별 필터</a></li> <li><a href="#_엣지_유형별로_필터링">엣지 유형별로 필터링</a></li> <li><a href="#_노드_유형_및_신뢰도로_필터링">노드 유형 및 신뢰도로 필터링</a></li> <li><a href="#_사용자_지정_출력_디렉터리">사용자 지정 출력 디렉터리</a></li> <li><a href="#_속성_전체_참조">속성 전체 참조</a></li> </ul> </li> <li><a href="#_gradle_워크플로우의_전체_파이프라인">Gradle 워크플로우의 전체 파이프라인</a> <ul class="sectlevel2"> <li><a href="#_워크플로_유형">워크플로 유형</a></li> <li><a href="#_개발_사이클에_통합">개발 사이클에 통합</a></li> <li><a href="#_증분_업데이트">증분 업데이트</a></li> </ul> </li> <li><a href="#_도그푸딩_플러그인은_스스로를_문서화한다">도그푸딩: 플러그인은 스스로를 문서화한다.</a></li> <li><a href="#_왜_그것이_결정적이며_그리고_왜_그것이_중요한가">왜 그것이 결정적이며 (그리고 왜 그것이 중요한가)</a></li> <li><a href="#_파이프라인_자체_다이어그램">파이프라인 자체 다이어그램</a></li> <li><a href="#_프로젝트_거버넌스_내_통합">프로젝트 거버넌스 내 통합</a></li> <li><a href="#_준비_5분_체크리스트">준비 : 5분 체크리스트</a></li> <li><a href="#_함정_및_완화_방안">함정 및 완화 방안</a></li> <li><a href="#_최종적으로_얻는_것">최종적으로 얻는 것</a></li> <li><a href="#_링크">링크</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽기 시간 : 12 minutes</div> <p>당신의 코드베이스가 커지고 있습니다. 모듈 간의 의존성이 늘어납니다. 아키텍처 문서는 작성되기도 전에 구식이 됩니다. 만약 Gradle 빌드가 <em>자동으로</em> 실제 코드 구조로부터 최신 다이어그램을 생성할 수 있다면? 이는 정확히 <code>pipeline Graphify + PlantUML Gradle Plugin</code> :`graphify . --no-viz`Knowledge Graph을 추출합니다,`./gradlew generateKnowledgeGraphDiagram`이를 PlantUML 다이어그램으로 변환합니다. LLM 없음, 매뉴얼 없음, 100% 결정적.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">톡</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_문제_항상_코드보다_뒤처진_다이어그램">문제: 항상 코드보다 뒤처진 다이어그램</h2> <div class="sectionbody"> <div class="paragraph"> <p>몇천 줄을 넘는 모든 프로젝트는 이 증후군을 겪는다 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>프로젝트 초기에 아키텍처 다이어그램을 그립니다.</p> </li> <li> <p>코드가 진화하고, 의존성이 바뀝니다.</p> </li> <li> <p>도표는 장식적인 거짓이 된다.</p> </li> <li> <p>아무도 이것을 업데이트하지 않아요, 왜냐하면 귀찮기 때문이에요</p> </li> <li> <p>신규 사용자들은 그것에 기반을 두고 실수를 합니다.</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam ActivityBackgroundColor #FDEDEC skinparam ActivityDiamondBackgroundColor #FFF3CD start :Diagramme d'architecture créé\n(manuellement, à la main); :Le code évolue\n(nouvelles classes, nouvelles dépendances); :Diagramme obsolète\n(ne reflète plus le code); if (Qui met à jour ?) then (Personne) :Documentation mensongère; note right: Les nouveaux développeurs\nse basent dessus... et font des erreurs else (Quelqu'un) :Mise à jour manuelle\n(2-3 heures de travail); note right: Déjà obsolète\nà la prochaine PR endif stop @enduml</pre> </div> </div> <div class="paragraph"> <p>질문은 <em>도표가 필요한가요?</em> — 모두가 알다시피 그렇습니다. 질문은 :<strong>누가 그들을 최신 상태로 유지합니까?</strong></p> </div> <div class="paragraph"> <p>답변 : 아무도 없습니다. 자동인 경우를 제외하고</p> </div> </div> </div> <div class="sect1"> <h2 id="_해결책_결정적_파이프라인_knowledge_graph_plantuml">해결책: 결정적 파이프라인 Knowledge Graph → PlantUML</h2> <div class="sectionbody"> <div class="paragraph"> <p>원칙은 간단합니다: 손으로 다이어그램을 그리는 대신에, 우리는 그들을,<strong>실제 코드 구조에서 생성</strong>.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle actor Développeur component "Graphify (pip install graphifyy)" as Graphify collections "graphify-out/graph.json (지식 그래프)" as KGJSON component "PlantUML Gradle Plugin\n(generateKnowledgeGraphDiagram)" as Plugin component "KnowledgeGraphParser" as Parser component "KnowledgeGraphRenderer" as Renderer component "PlantumlService (검증 + 렌더링 PNG)" as PS collections "diagrams/knowledge-graph/ (.puml + .png)" as Output Développeur --> Graphify : graphify . --no-viz Graphify --> KGJSON : extrait la structure\ndu code source Développeur --> Plugin : ./gradlew generateKnowledgeGraphDiagram Plugin --> Parser : parse(graph.json) Parser --> Plugin : KnowledgeGraph\n(noeuds + arêtes + communautés) Plugin --> Renderer : render(graph, filters) Renderer --> Plugin : code PlantUML\ndéterministe Plugin --> PS : validateSyntax + generateImage PS --> Output : .puml + .png note bottom of Plugin Pipeline DÉTERMINISTE Aucun appel LLM Résultat reproductible end note @enduml</pre> </div> </div> <div class="paragraph"> <p>두 개의 명령어. 그게 전부입니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Étape 1 : extraire le Knowledge Graph graphify . --no-viz # Étape 2 : générer les diagrammes PlantUML ./gradlew generateKnowledgeGraphDiagram</code></pre> </div> </div> <div class="paragraph"> <p>결과? 파일들`.puml` et <code>.png`안에`diagrams/knowledge-graph/</code>, Git에서 버전 관리된, 코드와 항상 최신 상태인</p> </div> </div> </div> <div class="sect1"> <h2 id="_단계_1_graphify_설치_및_knowledge_graph_추출">단계 1 : Graphify 설치 및 Knowledge Graph 추출</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_설치">설치</h3> <div class="paragraph"> <p>Graphify는 코드베이스를 분석하고 구조화된 지식 그래프를 구축하는 Python 도구입니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Méthode recommandée uv tool install graphifyy && graphify install --platform opencode # Alternative avec pip pip install graphifyy && graphify install --platform opencode</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_제외_항목_구성">제외 항목 구성</h3> <div class="paragraph"> <p>파일 생성`.graphifyignore`프로젝트 루트에 비즈니스 로직과 관련 없는 파일을 제외하기 위해:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-gitignore hljs" data-lang="gitignore"># Secrets — JAMAIS dans le graphe *-context.yml *.env # Fichiers générés build/ .gradle/ # Tests fonctionnels src/functionalTest/</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_지식_그래프_추출">지식 그래프 추출</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">graphify . --no-viz</code></pre> </div> </div> <div class="paragraph"> <p>플래그`--no-viz`HTML 생성을 건너뛰습니다 (Gradle 파이프라인에서는 불필요함). 결과는 파일입니다.`graphify-out/graph.json`포함 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>매듭들</strong>: 클래스, 함수, 파일 — 그들의 유형과 커뮤니티</p> </li> <li> <p><strong>모서리</strong>:노드간 관계(EXTRACTED 코드에서, INFERRED LLM에 의해)</p> </li> <li> <p><strong>커뮤니티</strong>연결된 노드의 자동 그룹화</p> </li> </ul> </div> <div class="listingblock"> <div class="title">예시 구조`graph.json`</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{ "nodes": [ {"id": "0", "label": "LlmService", "file_type": "code", "community": 0}, {"id": "1", "label": "ApiKeyPool", "file_type": "code", "community": 0}, {"id": "2", "label": "PlantumlService", "file_type": "code", "community": 1} ], "links": [ {"source": "1", "target": "0", "relation": "uses", "confidence": "EXTRACTED", "weight": 0.9}, {"source": "0", "target": "2", "relation": "calls", "confidence": "INFERRED", "weight": 0.7} ] }</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>소스 코드 (<code>.kt</code>, <code>.java</code>)는 tree-sitter에 의해 로컬에서 분석됩니다,<strong>항소할 수 없는 LLM</strong>. 문서 파일들만 (<code>.adoc</code>, <code>.md</code>) 의미 추출을 위해서는 LLM 호출이 필요합니다. 따라서`--update`Kotlin 코드를 컴파일하는 것은 거의 순간적입니다.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_단계_2_gradle_플러그인이_knowledge_graph를_plantuml로_변환합니다">단계 2 : Gradle 플러그인이 Knowledge Graph를 PlantUML로 변환합니다.</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_파이프라인_아키텍처">파이프라인 아키텍처</h3> <div class="paragraph"> <p>플러그인`com.cheroliv.plantuml`작업을 통합한다`generateKnowledgeGraphDiagram`이 변환하는`graph.json`en PlantUML 다이어그램 방식으로<strong>완전하게 결정적</strong>:</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE participant "Gradle" as G participant "지식 그래프 다이어그램 생성 작업" as Task participant "지식 그래프 파서" as Parser participant "KnowledgeGraphRenderer" as Renderer participant "PlantumlService" as PS collections "graphify-out/graph.json" as JSON G -> Task : execute Task -> JSON : read Task -> Parser : parse(graph.json) Parser --> Task : KnowledgeGraph\n(noeuds + arêtes + communautés) Task -> Renderer : render(graph, filters) Renderer --> Task : code PlantUML\n(déterministe) Task -> PS : validateSyntax(plantumlCode) alt syntaxe valide Task -> PS : generateImage → .png else syntaxe invalide Task -> Task : save .puml avec warning end @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_내부_구성_요소">내부 구성 요소</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">구성 요소</th> <th class="tableblock halign-left valign-top">역할</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>KnowledgeGraphParser</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">파싱`graph.json`— 3가지 형식 지원:네이티브 graphify (<code>nodes</code>+<code>links</code>), 유산 (")<code>communities</code>), 평평한. 숫자 ID를 레이블로 해결합니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>KnowledgeGraphRenderer</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">결정론적으로 변환해`KnowledgeGraph`PlantUML 코드에서. 유형별 그룹, 패키지 내 커뮤니티, 자동 범례.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>GenerateKnowledgeGraphDiagramTask</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Gradle 작업이 오케스트레이션: parse → render → validate → PNG. Gradle 속성을 통해 구성 가능.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>kgmodels.kt</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">데이터 모델:`KnowledgeGraph`, <code>KnowledgeGraphNode</code>, <code>KnowledgeGraphEdge</code>, <code>KnowledgeGraphCommunity</code>, <code>EdgeType</code>.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>PlantumlService</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">문법 검증 + PNG 렌더링 (플러그인의 모든 작업에서 재사용됨).</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_렌더링_규칙">렌더링 규칙</h3> <div class="paragraph"> <p>렌더러는 결정적인 시각적 관행을 적용합니다:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">엣지 타입</th> <th class="tableblock halign-left valign-top">표기법 PlantUML</th> <th class="tableblock halign-left valign-top">의미</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">추출된</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-→</code>(실선, 검정)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">소스 코드에서 추출된 관계 (확실성)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">추론된</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>..></code>(점선)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">LLM에 의해 추론된 관계 (신뢰 점수)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">모호한</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>--x</code>(빨간 점선)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">애매한 관계 (확인 필요)</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>커뮤니티는 자동 색상 팔레트가 적용된 PlantUML 패키지처럼 렌더링됩니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_3단계_일상_사용">3단계: 일상 사용</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_완전한_다이어그램">완전한 다이어그램</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Générer le diagramme du Knowledge Graph complet ./gradlew generateKnowledgeGraphDiagram</code></pre> </div> </div> <div class="paragraph"> <p>출력 :`diagrams/knowledge-graph/knowledge-graph-full.puml`+<code>.png</code></p> </div> </div> <div class="sect2"> <h3 id="_커뮤니티별_필터">커뮤니티별 필터</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Une seule communauté ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.community=community_0 # Limiter le nombre de noeuds (lisibilité) ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.community=community_0 \ -Pplantuml.kg.maxNodes=15</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_엣지_유형별로_필터링">엣지 유형별로 필터링</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Uniquement les relations certaines (EXTRACTED) ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.edgeTypes=EXTRACTED # Relations certaines + inférées ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.edgeTypes=EXTRACTED,INFERRED</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_노드_유형_및_신뢰도로_필터링">노드 유형 및 신뢰도로 필터링</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Uniquement les classes de code ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.nodeTypes=code # Seuil de confiance minimum (pour les INFERRED) ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.minConfidence=0.7</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_사용자_지정_출력_디렉터리">사용자 지정 출력 디렉터리</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.outputDir=docs/architecture</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_속성_전체_참조">속성 전체 참조</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">재산</th> <th class="tableblock halign-left valign-top">결함</th> <th class="tableblock halign-left valign-top">설명</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.community</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(모두)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">이름으로 커뮤니티 필터링 (부분 문자열 일치)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.edgeTypes</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><em>(모두)</em></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">콤마로 구분된 모서리 유형:`EXTRACTED`, <code>INFERRED</code>, <code>AMBIGUOUS</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.minConfidence</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>0.0</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">엣지에 대한 최소 신뢰도 임계값</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.maxNodes</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><em>(무한한)</em></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">표시할 최대 노드 수</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.nodeTypes</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(모두)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">콤마로 구분된 노드 유형 (예`class`, <code>code</code>)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.outputDir</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>diagrams/knowledge-graph</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">파일을 위한 출력 디렉터리`.puml` et <code>.png</code></p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_gradle_워크플로우의_전체_파이프라인">Gradle 워크플로우의 전체 파이프라인</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_워크플로_유형">워크플로 유형</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam ActivityBackgroundColor #E8F4FD skinparam ActivityDiamondBackgroundColor #FFF3CD skinparam ActivityBorderColor #2C3E50 start partition "추출" { :graphify . --no-viz; note right: Analyse le code source\ntree-sitter (local, pas de LLM) :graphify-out/graph.json; note right: Noeuds + arêtes\n+ communautés } partition "세대" { :./gradlew generateKnowledgeGraphDiagram; note right: Pipeline déterministe\nparse → render → validate → PNG if (Filtres actifs ?) then (Oui) :Appliquer filtres\n(community, edgeTypes,\nmaxNodes, nodeTypes); else (Non) :Diagramme complet; endif :diagrams/knowledge-graph/\nknowledge-graph-full.puml\nknowledge-graph-full.png; } partition "통합" { :git add diagrams/knowledge-graph/; :git commit; note right: Diagrammes versionnés\ntoujours à jour avec le code } stop @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_개발_사이클에_통합">개발 사이클에 통합</h3> <div class="paragraph"> <p>파이프라인은 개발의 핵심 단계에 자연스럽게 통합됩니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE state "개발" as dev state "추출 graphify . --no-viz" as extract state "생성 ./gradlew generateKnowledgeGraphDiagram" as generate state "커밋 버전 관리된 다이어그램" as commit [*] --> dev dev --> extract : Code modifié extract --> generate : graph.json à jour generate --> commit : .puml + .png générés commit --> dev : Diagrammes dans le repo note right of extract Quasi instantané sur du code Kotlin (tree-sitter, pas de LLM) end note note right of generate Déterministe Pas de LLM Résultat reproductible end note @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_증분_업데이트">증분 업데이트</h3> <div class="paragraph"> <p>코드가 변경될 때 전체 그래프를 처음부터 다시 구축하지 않는다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Mise à jour incrémentale (fichiers modifiés uniquement) graphify . --update # Puis régénérer les diagrammes ./gradlew generateKnowledgeGraphDiagram</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p><code>--update`수정된 파일만 다시 추출합니다 (SHA256로 감지된`graphify-out/cache/</code>). Kotlin 코드에서는 tree-sitter가 로컬에서 작동하여 LLM 호출 없이 거의 즉시 이루어집니다.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_도그푸딩_플러그인은_스스로를_문서화한다">도그푸딩: 플러그인은 스스로를 문서화한다.</h2> <div class="sectionbody"> <div class="paragraph"> <p>PlantUML 플러그인은 프롬프트를 다이어그램으로 변환하기 위해 존재합니다. 또한 자체 <em>propre</em> 코드베이스의 Knowledge Graph를 문서화 다이어그램으로 변환할 수도 있습니다. 이것은 _dogfooding_입니다: 플러그인은 자신의 서비스를 소비합니다.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "정상 파이프라인 (사용자 → 다이어그램)" as normal { [Fichier .prompt] as prompt [LlmService\n+ ApiKeyPool] as llm1 [ProcessPlantumlPromptsTask] as task1 [Diagramme PNG] as out1 prompt --> task1 task1 --> llm1 llm1 --> out1 } package "파이프라인 지식 그래프 (결정적, LLM 없음)" as kg { [graphify-out/graph.json] as kgjson [KnowledgeGraphParser] as parser [KnowledgeGraphRenderer] as renderer [PlantumlService] as ps [Diagramme PNG\n(documentation du plugin)] as out2 kgjson --> parser parser --> renderer renderer --> ps ps --> out2 } package "Pipeline Dogfooding (LLM → 플러그인 문서)" as dogfood { [GraphifyPromptAdapter] as gpa [Fichiers .prompt\nauto-générés] as auto_prompt [LlmService\n+ ApiKeyPool] as llm2 [ProcessPlantumlPromptsTask] as task2 [Diagramme PNG\n(documentation LLM)] as out3 kgjson --> gpa gpa --> auto_prompt auto_prompt --> task2 task2 --> llm2 llm2 --> out3 } note "LlmService, ApiKeyPool도 동일하고, PlantumlService도 동일합니다 — 중복 없음" as N @enduml</pre> </div> </div> <div class="paragraph"> <p>연관된 Gradle 작업 :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">작업</th> <th class="tableblock halign-left valign-top">LLM ?</th> <th class="tableblock halign-left valign-top">설명</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>generateKnowledgeGraphDiagram</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">아니요</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">변환해`graph.json`PlantUML에서 (결정적)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>generateDiagramDocs</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">예</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">생성해`.prompt`그래프에서부터, LLM(도그푸딩)를 통해 그들을 처리한다</p></td> </tr> </tbody> </table> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Documentation déterministe (rapide, pas de LLM) ./gradlew generateKnowledgeGraphDiagram # Documentation LLM (plus riche, consomme des tokens) ./gradlew generateDiagramDocs</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_왜_그것이_결정적이며_그리고_왜_그것이_중요한가">왜 그것이 결정적이며 (그리고 왜 그것이 중요한가)</h2> <div class="sectionbody"> <div class="paragraph"> <p>파이프라인의 핵심 지점`generateKnowledgeGraphDiagram`:<strong>그는 어떤 LLM도 부르지 않는다.</strong>. 변환`graph.json`→ PlantUML은 순수 함수이다.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle rectangle "결정적 파이프라인\n`generateKnowledgeGraphDiagram" as det { [graph.json] as json [KnowledgeGraphParser] as parser [KnowledgeGraphRenderer] as renderer [PlantUML code] as puml json --> parser : parse parser --> renderer : KnowledgeGraph renderer --> puml : render (fonction pure) } rectangle "파이프라인 LLM (processPlantumlPrompts)" as llm { [.prompt] as prompt [LlmService] as llmSvc [ChatModel] as model [PlantUML code] as puml2 prompt --> llmSvc llmSvc --> model : API call model --> puml2 : réponse non-déterministe } note bottom of det Même entrée → même sortie Pas de latence réseau Pas de coût en tokens Reproductible en CI end note note bottom of llm Même entrée → sortie variable Latence réseau (1-5s) Coût en tokens Nécessite une clave API end note @enduml</pre> </div> </div> <div class="paragraph"> <p>구체적인 이점:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">장점</th> <th class="tableblock halign-left valign-top">영향</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">재현성</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">같은`graph.json`→ 같은 다이어그램입니다. 정확히. 매번.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">제로 비용</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">LLM 호출 없음 = 토큰 없음 = API 청구서 없음</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">지연 없음</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Parse + render은 약 100ms가 소요되며, 1-5초가 아닙니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">CI 호환</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">API 키가 필요하지 않습니다. 변동적인 LLM 응답으로 인한 불안정한 테스트가 없습니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">버전 가능</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Le <code>.puml`생성된 텍스트는 텍스트입니다. 우리는 그것을`diff</code>, PR의 리뷰어, Git에서 버전 관리하기</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_파이프라인_자체_다이어그램">파이프라인 자체 다이어그램</h2> <div class="sectionbody"> <div class="paragraph"> <p>루프를 닫기 위해, 플러그인이 생성할 파이프라인 다이어그램은 다음과 같습니다:</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE participant "개발자" as Dev participant "그레이들" as G participant "지식 그래프 다이어그램 생성 태스크" as Task participant "지식 그래프 파서" as Parser participant "지식 그래프 렌더러" as Renderer participant "PlantUML서비스" as PS collections "graphify-out/graph.json" as JSON collections "다이어그램/지식-그래프/" as Out Dev -> G : ./gradlew generateKnowledgeGraphDiagram G -> Task : execute Task -> JSON : read Task -> Parser : parse(graph.json) Parser --> Task : KnowledgeGraph alt filtres actifs Task -> Task : appliquer filtres\n(community, edgeTypes, maxNodes…) end Task -> Renderer : render(graph, filters) Renderer --> Task : code PlantUML Task -> PS : validateSyntax() alt valide Task -> PS : generateImage() PS --> Out : .puml + .png else invalide Task -> Out : .puml (avec warning) end @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_프로젝트_거버넌스_내_통합">프로젝트 거버넌스 내 통합</h2> <div class="sectionbody"> <div class="paragraph"> <p>우리 프로젝트에서 이 파이프라인은 AI 에이전트를 위한 EAGER/LAZY 컨텍스트 관리 전략에 통합됩니다. Knowledge Graph는 수동 아키텍처 문서를 구조화되고 질의 가능하며 자동으로 업데이트되는 그래프로 대체합니다.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "EAGER\n(항상 충전된)" as eager { [PROMPT_REPRISE.adoc\n(contexte session)] as pr [INDEX.adoc\n(vue d'ensemble)] as idx [GRAPH_REPORT.adoc\n(~50 lignes)] as gr } package "LAZY — 전략 (요청 시)" as lazy_strat { [Méthodologies] as meth [Archives sessions] as sessions } package "LAZY — Graphify (대상 쿼리)" as lazy_graph { [graph.json] as gj [Queries\n(query/path/explain)] as queries } package "Pipeline PlantUML\n(자동 생성된)" as puml { [generateKnowledgeGraphDiagram] as kgTask [generateDiagramDocs] as ddTask [Diagrammes PNG] as diagrams } Agent --> eager : Lit en début de session Agent ..> lazy_strat : Charge si type détecté Agent ..> lazy_graph : Query si besoin structurel kgTask --> diagrams : Déterministe ddTask --> diagrams : Via LLM note right of gr Condensé du Knowledge Graph God nodes + communautés Remplace ECOSYSTEM_OVERVIEW (225 lignes → 50 lignes) end note @enduml</pre> </div> </div> <div class="paragraph"> <p>두 시스템의 결합은 보완적이다 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>전략은 언제와 어떻게를 관리합니다</strong>— 거버넌스, 워크플로우, 아카이빙</p> </li> <li> <p><strong>Graphify는 무엇과 어디를 관리합니다.</strong>— 코드 구조, 관계, 대상 쿼리</p> </li> </ul> </div> <div class="paragraph"> <p><em>__</em> 세션 전략이 관리하는<strong>언제</strong> et le <strong>어떻게</strong>(거버넌스, 워크플로우, 임계값), Graphify가 관리하는<strong>뭐</strong> et le <strong>어디</strong>(코드 구조, 관계, 대상 쿼리). 이 PlantUML 파이프라인이 그것을 관리한다.<strong>무엇으로</strong>(결정적, 버전 관리된, 항상 최신 상태인 다이어그램). </think></p> </div> </div> </div> <div class="sect1"> <h2 id="_준비_5분_체크리스트">준비 : 5분 체크리스트</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">#</th> <th class="tableblock halign-left valign-top">단계</th> <th class="tableblock halign-left valign-top">명령</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Graphify 설치</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>uv tool install graphifyy</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">제외 사항 구성</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">만들다`.graphifyignore`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Knowledge Graph 추출</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>graphify . --no-viz</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">다이어그램 생성</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>./gradlew generateKnowledgeGraphDiagram</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">결과를 커밋하다</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>git add diagrams/knowledge-graph/</code></p></td> </tr> </tbody> </table> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Script complet en 5 commandes uv tool install graphifyy cat > .graphifyignore << 'EOF' *-context.yml *.env build/ .gradle/ EOF graphify . --no-viz ./gradlew generateKnowledgeGraphDiagram git add graphify-out/GRAPH_REPORT.adoc graphify-out/graph.json diagrams/knowledge-graph/</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_함정_및_완화_방안">함정 및 완화 방안</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">함정</th> <th class="tableblock halign-left valign-top">설명</th> <th class="tableblock halign-left valign-top">완화</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">너무 빽빽한 그래프</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">큰 프로젝트는 수백 개의 읽을 수 없는 노드를 생성한다</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">사용하다`-Pplantuml.kg.maxNodes=30`그리고 커뮤니티별로 필터링</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">너무 넓은 제외 사항</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">안에 파일이 너무 많음`.graphifyignore`그래프의 값을 줄입니다</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">먼저 credentials와 build만 제외하고 시작</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">화살표의 방향</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">INFERRED 엣지는 방향이 모호할 수 있다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">필터 기준`-Pplantuml.kg.edgeTypes=EXTRACTED`확실한 관계에만</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">구식 그래프</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">코드가 변경되지만 그래프는 재구축되지 않습니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">사용하다`graphify . --update`정기적으로 또는 git 후크`graphify hook install`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">업데이트된 비용</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">증분 업데이트는 거의 무료입니다 (tree-sitter 로컬)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">문서들만 (<code>.adoc</code>) LLM 토큰을 소비합니다</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_최종적으로_얻는_것">최종적으로 얻는 것</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE rectangle "이전" as avant { card "수작업으로 그린 다이어그램 항상 구식 아무도 업데이트하지 않는다" as av1 #FDEDEC } rectangle "후" as apres { card "자동 생성된 다이어그램\n항상 코드와 최신 상태\nGit에서 버전 관리됨\n결정적이고 재현 가능" as ap1 #E8F8E8 } avant --> apres : graphify . --no-viz\n+ ./gradlew generateKnowledgeGraphDiagram @enduml</pre> </div> </div> <div class="paragraph"> <p>구체적인 혜택 :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">수익</th> <th class="tableblock halign-left valign-top">세부</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">항상 최신 문서</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">다이어그램은 현재 코드를 반영하고, 수동 스냅샷이 아닙니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">유지보수 노력이 제로</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">다이어그램은 매 빌드마다 재생성됩니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">기술 부채 감소</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">더 이상 다이어그램을 수동으로 유지할 필요가 없습니다</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">새로운 것을 위한 시각적 컨텍스트</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">새로운 개발자는 다이어그램을 보고 아키텍처를 이해한다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">파인튜닝 잠재력</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">서브그래프 → 다이어그램 쌍은 AI 훈련의 예시입니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">자동 검증</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`PlantumlService.validateSyntax()`생성된 각 다이어그램을 확인합니다</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">빠른 온보딩</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">5개의 다이어그램 = 아키텍처의 완전한 뷰</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><em><em>_ _pourquoi_를 가진 사람은 모든 _comment_을 견딜 수 있다. </em>_</em></p> </div> <div class="paragraph"> <p><em>왜</em> : 항상 최신인 다이어그램. <em>어떻게</em> : Gradle 파이프라인 내의 두 명령어.</p> </div> </div> </div> <div class="sect1"> <h2 id="_링크">링크</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://github.com/nicholasgasior/graphify">GitHub의 Graphify</a></p> </li> <li> <p><a href="https://github.com/cheroliv/plantuml-gradle">PlantUML Gradle 플러그인</a></p> </li> <li> <p><a href="/blog/2026/0104_fg_command_super_tips_post.html">fg 명령의 슈퍼 팁</a>— 터미널 워크플로우에 대한 이전 기사</p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0105_integrer_graphify_workflow_gradle_post.html Sun, 19 Apr 2026 00:00:00 +0000 blog/2026/0105_integrer_graphify_workflow_gradle_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_문제_다이어그램이_언제나_코드보다_뒤처진다">문제: 다이어그램이 언제나 코드보다 뒤처진다</a></li> <li><a href="#_솔루션_결정적_knowledge_graph_plantuml_파이프라인">솔루션 : 결정적 Knowledge Graph → PlantUML 파이프라인</a></li> <li><a href="#_단계_1_graphify_설치_및_knowledge_graph_추출">단계 1: Graphify 설치 및 Knowledge Graph 추출</a> <ul class="sectlevel2"> <li><a href="#_설치">설치</a></li> <li><a href="#_제외_사항_구성">제외 사항 구성</a></li> <li><a href="#_지식_그래프_추출">지식 그래프 추출</a></li> </ul> </li> <li><a href="#_2단계_gradle_플러그인이_knowledge_graph를_plantuml로_변환합니다">2단계: Gradle 플러그인이 Knowledge Graph를 PlantUML로 변환합니다.</a> <ul class="sectlevel2"> <li><a href="#_파이프라인_아키텍처">파이프라인 아키텍처</a></li> <li><a href="#_내부_구성_요소">내부 구성 요소</a></li> <li><a href="#_렌더링_규칙">렌더링 규칙</a></li> </ul> </li> <li><a href="#_단계_3_일상_사용">단계 3: 일상 사용</a> <ul class="sectlevel2"> <li><a href="#_완전한_다이어그램">완전한 다이어그램</a></li> <li><a href="#_커뮤니티별_필터">커뮤니티별 필터</a></li> <li><a href="#_엣지_유형별로_필터">엣지 유형별로 필터</a></li> <li><a href="#_노드_유형과_신뢰도로_필터링">노드 유형과 신뢰도로 필터링</a></li> <li><a href="#_사용자_지정_출력_디렉터리">사용자 지정 출력 디렉터리</a></li> <li><a href="#_속성에_대한_완전한_참조">속성에 대한 완전한 참조</a></li> </ul> </li> <li><a href="#_gradle_워크플로우의_전체_파이프라인">Gradle 워크플로우의 전체 파이프라인</a> <ul class="sectlevel2"> <li><a href="#_워크플로_유형">워크플로 유형</a></li> <li><a href="#_개발_주기_통합">개발 주기 통합</a></li> <li><a href="#_증분_업데이트">증분 업데이트</a></li> </ul> </li> <li><a href="#_도그푸딩_플러그인이_스스로_문서화한다">도그푸딩: 플러그인이 스스로 문서화한다</a></li> <li><a href="#_왜_그것이_결정적인가_그리고_왜_중요한가">왜 그것이 결정적인가 (그리고 왜 중요한가)</a></li> <li><a href="#_파이프라인_자체의_다이어그램">파이프라인 자체의 다이어그램</a></li> <li><a href="#_프로젝트_거버넌스_내_통합">프로젝트 거버넌스 내 통합</a></li> <li><a href="#_준비_5분_체크리스트">준비: 5분 체크리스트</a></li> <li><a href="#_함정과_완화">함정과 완화</a></li> <li><a href="#_결과적으로_얻는_것">결과적으로 얻는 것</a></li> <li><a href="#_링크">링크</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽기 시간 : 12 minutes</div> <p>코드베이스가 커지고 있습니다. 모듈 간의 의존성이 점점 늘어나고 있습니다. 아키텍처 문서는 작성되기도 전에 이미 오래됩니다. 그리고 Gradle 빌드가 <em>자동으로</em> 실제 코드 구조에서 최신 다이어그램을 생성할 수 있다면? 이게 바로 Graphify + PlantUML Gradle Plugin 파이프라인이 하는 일입니다:`graphify . --no-viz`Knowledge Graph를 추출,`./gradlew generateKnowledgeGraphDiagram`PlantUML 다이어그램으로 변환합니다. 제로 LLM, 제로 매뉴얼, 100% 결정적.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">강박</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_문제_다이어그램이_언제나_코드보다_뒤처진다">문제: 다이어그램이 언제나 코드보다 뒤처진다</h2> <div class="sectionbody"> <div class="paragraph"> <p>몇천 줄을 넘는 모든 프로젝트는 이 증후군을 경험합니다:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>프로젝트 초기에 아키텍처 다이어그램을 그립니다.</p> </li> <li> <p>코드가 진화하고, 의존성이 변경됩니다.</p> </li> <li> <p>다이어그램은 장식적인 거짓말이 된다</p> </li> <li> <p>아무도 업데이트하지 않아요, 왜냐하면 그게 귀찮기 때문이에요</p> </li> <li> <p>신규 사용자들은 그것에 의존하여 실수를 합니다.</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam ActivityBackgroundColor #FDEDEC skinparam ActivityDiamondBackgroundColor #FFF3CD start :Diagramme d'architecture créé\n(manuellement, à la main); :Le code évolue\n(nouvelles classes, nouvelles dépendances); :Diagramme obsolète\n(ne reflète plus le code); if (Qui met à jour ?) then (Personne) :Documentation mensongère; note right: Les nouveaux développeurs\nse basent dessus... et font des erreurs else (Quelqu'un) :Mise à jour manuelle\n(2-3 heures de travail); note right: Déjà obsolète\nà la prochaine PR endif stop @enduml</pre> </div> </div> <div class="paragraph"> <p>질문은 <em>faut-il des diagrammes ?</em> 가 아니다 — 모두가 그렇다고 알고 있다. 질문은 :<strong>누가 그들을 최신 상태로 유지합니까?</strong></p> </div> <div class="paragraph"> <p>답변: 아무도 없습니다. 단, 자동인 경우에는 예외입니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_솔루션_결정적_knowledge_graph_plantuml_파이프라인">솔루션 : 결정적 Knowledge Graph → PlantUML 파이프라인</h2> <div class="sectionbody"> <div class="paragraph"> <p>원칙은 간단합니다 : 손으로 다이어그램을 그리는 대신, 우리는 그들을<strong>실제 코드 구조에서 생성한다</strong>.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle actor Développeur component "Graphify (pip install graphifyy)" as Graphify collections "graphify-out/graph.json (지식 그래프)" as KGJSON component "PlantUML Gradle 플러그인 (지식 그래프 다이어그램 생성)" as Plugin component "KnowledgeGraphParser" as Parser component "지식 그래프 렌더러" as Renderer component "PlantumlService (검증 + PNG 렌더링)" as PS collections "diagrams/knowledge-graph/\n(.puml + .png)" as Output Développeur --> Graphify : graphify . --no-viz Graphify --> KGJSON : extrait la structure\ndu code source Développeur --> Plugin : ./gradlew generateKnowledgeGraphDiagram Plugin --> Parser : parse(graph.json) Parser --> Plugin : KnowledgeGraph\n(noeuds + arêtes + communautés) Plugin --> Renderer : render(graph, filters) Renderer --> Plugin : code PlantUML\ndéterministe Plugin --> PS : validateSyntax + generateImage PS --> Output : .puml + .png note bottom of Plugin Pipeline DÉTERMINISTE Aucun appel LLM Résultat reproductible end note @enduml</pre> </div> </div> <div class="paragraph"> <p>두 개의 명령어. 그게 전부야.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Étape 1 : extraire le Knowledge Graph graphify . --no-viz # Étape 2 : générer les diagrammes PlantUML ./gradlew generateKnowledgeGraphDiagram</code></pre> </div> </div> <div class="paragraph"> <p>결과 ? 파일들`.puml` et <code>.png`안에`diagrams/knowledge-graph/</code>, Git에서 버전 관리되어 코드와 항상 최신 상태를 유지합니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_단계_1_graphify_설치_및_knowledge_graph_추출">단계 1: Graphify 설치 및 Knowledge Graph 추출</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_설치">설치</h3> <div class="paragraph"> <p>Graphify는 코드베이스를 분석하고 구조화된 지식 그래프를 구축하는 Python 도구입니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Méthode recommandée uv tool install graphifyy && graphify install --platform opencode # Alternative avec pip pip install graphifyy && graphify install --platform opencode</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_제외_사항_구성">제외 사항 구성</h3> <div class="paragraph"> <p>파일 만들기`.graphifyignore`프로젝트 루트에서 비즈니스 로직에 속하지 않는 파일을 제외하기 위해:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-gitignore hljs" data-lang="gitignore"># Secrets — JAMAIS dans le graphe *-context.yml *.env # Fichiers générés build/ .gradle/ # Tests fonctionnels src/functionalTest/</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_지식_그래프_추출">지식 그래프 추출</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">graphify . --no-viz</code></pre> </div> </div> <div class="paragraph"> <p>플래그`--no-viz`HTML 생성을 건너뛰세요 (Gradle 파이프라인에서는 불필요함). 결과는 파일입니다.`graphify-out/graph.json`포함 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>매듭</strong>: 클래스, 함수, 파일 — 유형과 커뮤니티와 함께</p> </li> <li> <p><strong>가시</strong>: 노드 간 관계 (EXTRACTED 코드에서, INFERRED LLM에 의해)</p> </li> <li> <p><strong>커뮤니티</strong>: 연결된 노드의 자동 그룹화</p> </li> </ul> </div> <div class="listingblock"> <div class="title">구조 예시`graph.json`</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{ "nodes": [ {"id": "0", "label": "LlmService", "file_type": "code", "community": 0}, {"id": "1", "label": "ApiKeyPool", "file_type": "code", "community": 0}, {"id": "2", "label": "PlantumlService", "file_type": "code", "community": 1} ], "links": [ {"source": "1", "target": "0", "relation": "uses", "confidence": "EXTRACTED", "weight": 0.9}, {"source": "0", "target": "2", "relation": "calls", "confidence": "INFERRED", "weight": 0.7} ] }</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>소스 코드 (<code>.kt</code>, <code>.java</code>) 로컬에서 tree-sitter에 의해 분석된다,<strong>이의를 제기할 수 없는 LLM</strong>. 문서 파일들만 (<code>.adoc</code>, <code>.md</code>) 그들이 의미 추출을 위해 LLM 호출이 필요합니다. 따라서`--update`Kotlin 코드 실행은 거의 즉시입니다.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_2단계_gradle_플러그인이_knowledge_graph를_plantuml로_변환합니다">2단계: Gradle 플러그인이 Knowledge Graph를 PlantUML로 변환합니다.</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_파이프라인_아키텍처">파이프라인 아키텍처</h3> <div class="paragraph"> <p>플러그인`com.cheroliv.plantuml`작업을 포함합니다`generateKnowledgeGraphDiagram`변환하는`graph.json`PlantUML 다이어그램 방식으로<strong>완전히 결정론적인</strong>:</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE participant "Gradle" as G participant "생성 지식 그래프 다이어그램 작업" as Task participant "KnowledgeGraphParser" as Parser participant "지식 그래프 렌더러" as Renderer participant "PlantumlService" as PS collections "graphify-out/graph.json" as JSON G -> Task : execute Task -> JSON : read Task -> Parser : parse(graph.json) Parser --> Task : KnowledgeGraph\n(noeuds + arêtes + communautés) Task -> Renderer : render(graph, filters) Renderer --> Task : code PlantUML\n(déterministe) Task -> PS : validateSyntax(plantumlCode) alt syntaxe valide Task -> PS : generateImage → .png else syntaxe invalide Task -> Task : save .puml avec warning end @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_내부_구성_요소">내부 구성 요소</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">컴포넌트</th> <th class="tableblock halign-left valign-top">역할</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>KnowledgeGraphParser</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">파싱하다`graph.json`— 3가지 형식을 지원합니다 : 네이티브 graphify (<code>nodes</code>+<code>links</code>), 레거시 (<code>communities</code>), flat. 숫자 ID를 라벨로 해결합니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>KnowledgeGraphRenderer</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">결정적으로 변환한다`KnowledgeGraph`PlantUML 코드. 유형별 그룹, 패키지 내 커뮤니티, 자동 범례.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>GenerateKnowledgeGraphDiagramTask</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Gradle 작업: 파싱 → 렌더링 → 검증 → PNG를 오케스트레이션합니다. Gradle 속성을 통해 구성할 수 있습니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>kgmodels.kt</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">데이터 모델:`KnowledgeGraph`, <code>KnowledgeGraphNode</code>, <code>KnowledgeGraphEdge</code>, <code>KnowledgeGraphCommunity</code>, <code>EdgeType</code>.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>PlantumlService</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">구문 검증 + PNG 렌더링 (플러그인의 모든 작업에서 재사용됨).</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_렌더링_규칙">렌더링 규칙</h3> <div class="paragraph"> <p>렌더러는 결정적인 시각적 규칙을 적용합니다:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">에지 유형</th> <th class="tableblock halign-left valign-top">PlantUML 표기법</th> <th class="tableblock halign-left valign-top">의미</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">추출된</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-→</code>(실선, 검정)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">소스 코드에서 추출된 (확실성)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">추론된</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>..></code>(점선)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">LLM이 추론한 관계 (신뢰도 점수)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">모호한</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>--x</code>(빨간 점선)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">모호한 관계 (확인 필요)</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>커뮤니티는 자동 색상 팔레트를 가진 PlantUML 패키지처럼 렌더링됩니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_단계_3_일상_사용">단계 3: 일상 사용</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_완전한_다이어그램">완전한 다이어그램</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Générer le diagramme du Knowledge Graph complet ./gradlew generateKnowledgeGraphDiagram</code></pre> </div> </div> <div class="paragraph"> <p>출력 :`diagrams/knowledge-graph/knowledge-graph-full.puml` + <code>.png</code></p> </div> </div> <div class="sect2"> <h3 id="_커뮤니티별_필터">커뮤니티별 필터</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Une seule communauté ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.community=community_0 # Limiter le nombre de noeuds (lisibilité) ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.community=community_0 \ -Pplantuml.kg.maxNodes=15</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_엣지_유형별로_필터">엣지 유형별로 필터</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Uniquement les relations certaines (EXTRACTED) ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.edgeTypes=EXTRACTED # Relations certaines + inférées ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.edgeTypes=EXTRACTED,INFERRED</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_노드_유형과_신뢰도로_필터링">노드 유형과 신뢰도로 필터링</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Uniquement les classes de code ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.nodeTypes=code # Seuil de confiance minimum (pour les INFERRED) ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.minConfidence=0.7</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_사용자_지정_출력_디렉터리">사용자 지정 출력 디렉터리</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.outputDir=docs/architecture</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_속성에_대한_완전한_참조">속성에 대한 완전한 참조</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">속성</th> <th class="tableblock halign-left valign-top">결함</th> <th class="tableblock halign-left valign-top">설명</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.community</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(모두)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">이름(부분 문자열 일치)로 커뮤니티 필터링</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.edgeTypes</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><em>(모든)</em></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">쉼표로 구분된 엣지 유형 :`EXTRACTED`, <code>INFERRED</code>, <code>AMBIGUOUS</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.minConfidence</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>0.0</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">엣지에 대한 최소 신뢰도 임계값</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.maxNodes</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(무제한)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">표시할 최대 노드 수</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.nodeTypes</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(모두)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">콤마로 구분된 노드 유형 (ex.<code>class</code>, <code>code</code>)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.outputDir</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>diagrams/knowledge-graph</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">파일용 출력 디렉터리`.puml` et <code>.png</code></p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_gradle_워크플로우의_전체_파이프라인">Gradle 워크플로우의 전체 파이프라인</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_워크플로_유형">워크플로 유형</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam ActivityBackgroundColor #E8F4FD skinparam ActivityDiamondBackgroundColor #FFF3CD skinparam ActivityBorderColor #2C3E50 start partition "추출" { :graphify . --no-viz; note right: Analyse le code source\ntree-sitter (local, pas de LLM) :graphify-out/graph.json; note right: Noeuds + arêtes\n+ communautés } partition "세대" { :./gradlew generateKnowledgeGraphDiagram; note right: Pipeline déterministe\nparse → render → validate → PNG if (Filtres actifs ?) then (Oui) :Appliquer filtres\n(community, edgeTypes,\nmaxNodes, nodeTypes); else (Non) :Diagramme complet; endif :diagrams/knowledge-graph/\nknowledge-graph-full.puml\nknowledge-graph-full.png; } partition "통합" { :git add diagrams/knowledge-graph/; :git commit; note right: Diagrammes versionnés\ntoujours à jour avec le code } stop @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_개발_주기_통합">개발 주기 통합</h3> <div class="paragraph"> <p>파이프라인은 개발의 주요 단계에 자연스럽게 통합됩니다:</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE state "개발" as dev state "Extraction\ngraphify . --no-viz" as extract state "생성 ./gradlew generateKnowledgeGraphDiagram" as generate state "커밋 버전 관리된 다이어그램" as commit [*] --> dev dev --> extract : Code modifié extract --> generate : graph.json à jour generate --> commit : .puml + .png générés commit --> dev : Diagrammes dans le repo note right of extract Quasi instantané sur du code Kotlin (tree-sitter, pas de LLM) end note note right of generate Déterministe Pas de LLM Résultat reproductible end note @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_증분_업데이트">증분 업데이트</h3> <div class="paragraph"> <p>코드가 변경되면 전체 그래프를 처음부터 다시 구축하지 않는다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Mise à jour incrémentale (fichiers modifiés uniquement) graphify . --update # Puis régénérer les diagrammes ./gradlew generateKnowledgeGraphDiagram</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p><code>--update`수정된 파일만 다시 추출 (SHA256로 감지된`graphify-out/cache/</code>). Kotlin 코드에서는 tree-sitter가 로컬에서 작동하고 LLM 호출이 없어 거의 즉시 처리됩니다.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_도그푸딩_플러그인이_스스로_문서화한다">도그푸딩: 플러그인이 스스로 문서화한다</h2> <div class="sectionbody"> <div class="paragraph"> <p>PlantUML 플러그인은 프롬프트를 다이어그램으로 변환하기 위해 존재합니다. 또한 자체 <em>propre</em> 코드베이스의 Knowledge Graph를 문서 다이어그램으로 변환할 수 있습니다. 이것은 _dogfooding_입니다: 플러그인은 자체 서비스를 소비합니다.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "정상 파이프라인 (사용자 → 다이어그램)" as normal { [Fichier .prompt] as prompt [LlmService\n+ ApiKeyPool] as llm1 [ProcessPlantumlPromptsTask] as task1 [Diagramme PNG] as out1 prompt --> task1 task1 --> llm1 llm1 --> out1 } package "파이프라인 지식 그래프 (결정론적, LLM 없음)" as kg { [graphify-out/graph.json] as kgjson [KnowledgeGraphParser] as parser [KnowledgeGraphRenderer] as renderer [PlantumlService] as ps [Diagramme PNG\n(documentation du plugin)] as out2 kgjson --> parser parser --> renderer renderer --> ps ps --> out2 } package "Pipeline Dogfooding (LLM → 플러그인 문서)" as dogfood { [GraphifyPromptAdapter] as gpa [Fichiers .prompt\nauto-générés] as auto_prompt [LlmService\n+ ApiKeyPool] as llm2 [ProcessPlantumlPromptsTask] as task2 [Diagramme PNG\n(documentation LLM)] as out3 kgjson --> gpa gpa --> auto_prompt auto_prompt --> task2 task2 --> llm2 llm2 --> out3 } note "같은 LlmService, 같은 ApiKeyPool, 같은 PlantumlService — 중복 없음" as N @enduml</pre> </div> </div> <div class="paragraph"> <p>연관된 Gradle 작업:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">작업</th> <th class="tableblock halign-left valign-top">LLM ?</th> <th class="tableblock halign-left valign-top">설명</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>generateKnowledgeGraphDiagram</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">아니요</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">변환해`graph.json`PlantUML (확정적)에서</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>generateDiagramDocs</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">예</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">생성해`.prompt`그래프에서부터, LLM(도그푸딩)을 통해 처리합니다.</p></td> </tr> </tbody> </table> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Documentation déterministe (rapide, pas de LLM) ./gradlew generateKnowledgeGraphDiagram # Documentation LLM (plus riche, consomme des tokens) ./gradlew generateDiagramDocs</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_왜_그것이_결정적인가_그리고_왜_중요한가">왜 그것이 결정적인가 (그리고 왜 중요한가)</h2> <div class="sectionbody"> <div class="paragraph"> <p>파이프라인의 핵심 포인트`generateKnowledgeGraphDiagram` : <strong>그는 어떤 LLM도 부르지 않는다.</strong>. 변환`graph.json`PlantUML은 순수 함수이다.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle rectangle "결정적 파이프라인 (generateKnowledgeGraphDiagram)" as det { [graph.json] as json [KnowledgeGraphParser] as parser [KnowledgeGraphRenderer] as renderer [PlantUML code] as puml json --> parser : parse parser --> renderer : KnowledgeGraph renderer --> puml : render (fonction pure) } rectangle "파이프라인 LLM\n(processPlantumlPrompts)" as llm { [.prompt] as prompt [LlmService] as llmSvc [ChatModel] as model [PlantUML code] as puml2 prompt --> llmSvc llmSvc --> model : API call model --> puml2 : réponse non-déterministe } note bottom of det Même entrée → même sortie Pas de latence réseau Pas de coût en tokens Reproductible en CI end note note bottom of llm Même entrée → sortie variable Latence réseau (1-5s) Coût en tokens Nécessite une clave API end note @enduml</pre> </div> </div> <div class="paragraph"> <p>구체적인 장점 :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">장점</th> <th class="tableblock halign-left valign-top">영향</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">재현성</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">같은`graph.json`→ 동일한 다이어그램. 정확히. 매번.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">제로 비용</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">LLM 호출이 없으면 토큰도 없고 API 청구서도 없습니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">제로 지연</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Parse + render는 약 100ms가 소요되며, 1-5초가 아닙니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">CI 호환</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">API 키가 필요하지 않습니다. 변동하는 LLM 응답으로 인한 불안정한 테스트가 없습니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">버전 가능한</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Le <code>.puml`생성된 것은 텍스트입니다. 그것을 할 수 있습니다.`diff</code>, PR의 리뷰어, Git에 버전 관리.</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_파이프라인_자체의_다이어그램">파이프라인 자체의 다이어그램</h2> <div class="sectionbody"> <div class="paragraph"> <p>루프를 마무리하기 위해, 플러그인이 생성할 파이프라인 다이어그램은 다음과 같습니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE participant "개발자" as Dev participant "그래들" as G participant "지식 그래프 다이어그램 생성 태스크" as Task participant "KnowledgeGraphParser" as Parser participant "KnowledgeGraphRenderer" as Renderer participant "PlantUML 서비스" as PS collections "graphify-out/graph.json" as JSON collections "diagrams/knowledge-graph/" as Out Dev -> G : ./gradlew generateKnowledgeGraphDiagram G -> Task : execute Task -> JSON : read Task -> Parser : parse(graph.json) Parser --> Task : KnowledgeGraph alt filtres actifs Task -> Task : appliquer filtres\n(community, edgeTypes, maxNodes…) end Task -> Renderer : render(graph, filters) Renderer --> Task : code PlantUML Task -> PS : validateSyntax() alt valide Task -> PS : generateImage() PS --> Out : .puml + .png else invalide Task -> Out : .puml (avec warning) end @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_프로젝트_거버넌스_내_통합">프로젝트 거버넌스 내 통합</h2> <div class="sectionbody"> <div class="paragraph"> <p>우리 프로젝트에서 이 파이프라인은 AI 에이전트를 위한 EAGER/LAZY 컨텍스트 관리 전략에 통합됩니다. Knowledge Graph는 수동 아키텍처 문서를 구조화되고 쿼리 가능하며 자동으로 업데이트되는 그래프로 대체합니다.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "EAGER (항상 충전된)" as eager { [PROMPT_REPRISE.adoc\n(contexte session)] as pr [INDEX.adoc\n(vue d'ensemble)] as idx [GRAPH_REPORT.adoc\n(~50 lignes)] as gr } package "LAZY — 전략\n(요청 시)" as lazy_strat { [Méthodologies] as meth [Archives sessions] as sessions } package "LAZY — Graphify (목표된 쿼리)" as lazy_graph { [graph.json] as gj [Queries\n(query/path/explain)] as queries } package "Pipeline PlantUML (자동 생성된)" as puml { [generateKnowledgeGraphDiagram] as kgTask [generateDiagramDocs] as ddTask [Diagrammes PNG] as diagrams } Agent --> eager : Lit en début de session Agent ..> lazy_strat : Charge si type détecté Agent ..> lazy_graph : Query si besoin structurel kgTask --> diagrams : Déterministe ddTask --> diagrams : Via LLM note right of gr Condensé du Knowledge Graph God nodes + communautés Remplace ECOSYSTEM_OVERVIEW (225 lignes → 50 lignes) end note @enduml</pre> </div> </div> <div class="paragraph"> <p>두 시스템의 결합은 보완적입니다 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>전략은 QUAND와 COMMENT를 관리합니다</strong>— 거버넌스, 워크플로우, 보관</p> </li> <li> <p><strong>Graphify는 WHAT과 WHERE를 관리합니다.</strong>— 코드 구조, 관계, 목표 쿼리</p> </li> </ul> </div> <div class="paragraph"> <p><em>__</em> 세션 전략은 를 관리합니다.<strong>언제</strong> et le <strong>어떻게</strong>(거버넌스, 워크플로우, 임계치), Graphify는それを 관리한다<strong>뭐</strong> et le <strong>어디</strong>(코드 구조, 관계, 대상 쿼리). PlantUML 파이프라인이 관리<strong>무엇으로</strong>(결정론적 다이어그램, 버전 관리된, 항상 최신). </think> (Empty)</p> </div> </div> </div> <div class="sect1"> <h2 id="_준비_5분_체크리스트">준비: 5분 체크리스트</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">#</th> <th class="tableblock halign-left valign-top">단계</th> <th class="tableblock halign-left valign-top">주문</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Graphify 설치</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>uv tool install graphifyy</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">제외 항목 구성</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">생성하다`.graphifyignore`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">지식 그래프 추출</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>graphify . --no-viz</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">다이어그램 생성</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>./gradlew generateKnowledgeGraphDiagram</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">결과를 커밋하다</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>git add diagrams/knowledge-graph/</code></p></td> </tr> </tbody> </table> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Script complet en 5 commandes uv tool install graphifyy cat > .graphifyignore << 'EOF' *-context.yml *.env build/ .gradle/ EOF graphify . --no-viz ./gradlew generateKnowledgeGraphDiagram git add graphify-out/GRAPH_REPORT.adoc graphify-out/graph.json diagrams/knowledge-graph/</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_함정과_완화">함정과 완화</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">함정</th> <th class="tableblock halign-left valign-top">설명</th> <th class="tableblock halign-left valign-top">완화</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">너무 빽빽한 그래프</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">큰 프로젝트는 수백 개의 읽을 수 없는 노드를 생성</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">사용하다`-Pplantuml.kg.maxNodes=30`그리고 커뮤니티별로 필터링</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">너무 넓은 제외</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">너무 많은 파일이`.graphifyignore`그래프의 값을 줄입니다</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">먼저 credentials와 build만 제외하기</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">화살 방향</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">INFERRED 엣지들은 방향이 모호할 수 있습니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">필터링 기준`-Pplantuml.kg.edgeTypes=EXTRACTED`확실한 관계에 대해서만</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">구식 그래프</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">코드는 바뀌지만 그래프는 재구축되지 않습니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">사용하다`graphify . --update`정기적으로 또는 git 후크`graphify hook install`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">업데이트된 비용</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">증분 업데이트는 거의 무료입니다 (tree-sitter local)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">문서만 (<code>.adoc</code>) LLM 토큰을 소비합니다</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_결과적으로_얻는_것">결과적으로 얻는 것</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE rectangle "전에" as avant { card "수작업으로 그린 다이어그램 항상 구식 아무도 업데이트하지 않는다" as av1 #FDEDEC } rectangle "이후" as apres { card "자동 생성된 다이어그램 항상 코드와 최신 상태 Git에서 버전 관리됨 결정적이고 재현 가능" as ap1 #E8F8E8 } avant --> apres : graphify . --no-viz\n+ ./gradlew generateKnowledgeGraphDiagram @enduml</pre> </div> </div> <div class="paragraph"> <p>실질적인 혜택 :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">이익</th> <th class="tableblock halign-left valign-top">세부</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">항상 최신 문서</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">다이어그램은 현재 코드를 반영하며, 수동 스냅샷이 아닙니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">유지 보수 노력 없음</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">다이어그램은 각 빌드마다 재생성됩니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">기술 부채 감소</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">다이어그램을 수동으로 유지할 필요가 없습니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">신규를 위한 시각적 맥락</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">새로운 개발자는 다이어그램을 보고 아키텍처를 이해한다</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">가능한 파인 튜닝</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(서브그래프 → 다이어그램) 쌍은 AI 훈련의 예시입니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">자동 검증</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`PlantumlService.validateSyntax()`생성된 각 다이어그램을 확인합니다</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">빠른 온보딩</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">5개 다이어그램 = 아키텍처의 완전한 뷰</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><em><em>_ 누가 _pourquoi_를 가지고 있으면 모든 _comment_을 감당할 수 있다. </em>_</em></p> </div> <div class="paragraph"> <p>왜냐하면 (<em>pourquoi</em>): 항상 최신 상태인 다이어그램. 어떻게 (<em>comment</em>): 그레이들 파이프라인에 두 개의 명령어가 있다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_링크">링크</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://github.com/nicholasgasior/graphify">GitHub에서 Graphify</a></p> </li> <li> <p><a href="https://github.com/cheroliv/plantuml-gradle">PlantUML Gradle 플러그인</a></p> </li> <li> <p><a href="/blog/2026/0104_fg_command_super_tips_post.html">명령어 fg의 슈퍼 팁</a>— 터미널 워크플로우에 대한 이전 기사</p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0104_fg_command_super_tips_post.html Sat, 18 Apr 2026 00:00:00 +0000 blog/2026/0104_fg_command_super_tips_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_문제_바쁜_터미널">문제 : 바쁜 터미널</a></li> <li><a href="#_세_가지_필수_명령어">세 가지 필수 명령어</a> <ul class="sectlevel2"> <li><a href="#_ctrlz_일시_중지_sigtstp">Ctrl+Z — 일시 중지 (SIGTSTP)</a></li> <li><a href="#_fg_앞으로_가져오기">fg — 앞으로 가져오기</a></li> <li><a href="#_bg_백그라운드에서_재개">bg — 백그라운드에서 재개</a></li> <li><a href="#_jobs_셸의_작업_목록_보기">jobs — 셸의 작업 목록 보기</a></li> </ul> </li> <li><a href="#_시나리오_1_긴_빌드">시나리오 1 : 긴 빌드</a> <ul class="sectlevel2"> <li><a href="#_한_걸음씩">한 걸음씩</a></li> </ul> </li> <li><a href="#_시나리오_2_잊어버린_편집자">시나리오 2 : 잊어버린 편집자</a></li> <li><a href="#_시나리오_3_opencode_프로세스가_일시_중지됨">시나리오 3: opencode 프로세스가 일시 중지됨</a></li> <li><a href="#_시나리오_4_여러_작업을_동시에_관리하기">시나리오 4 : 여러 작업을 동시에 관리하기</a> <ul class="sectlevel2"> <li><a href="#_작업_명령어_요약">작업 명령어 요약</a></li> </ul> </li> <li><a href="#_fg_bg_ctrlz_ctrlc_및_의_차이">fg, bg, Ctrl+Z, Ctrl+C 및 &의 차이</a></li> <li><a href="#_작업의_전체_수명_주기">작업의 전체 수명 주기</a></li> <li><a href="#_고급_팁">고급 팁</a> <ul class="sectlevel2"> <li><a href="#_fg와_가장_최근의_직업_및_교대">fg와 가장 최근의 직업 및 교대</a></li> <li><a href="#_작업을_깔끔하게_종료하다">작업을 깔끔하게 종료하다</a></li> <li><a href="#_disown_쉘에서_분리">disown : 쉘에서 분리</a></li> <li><a href="#_nohup과_결합하여_긴_프로세스를_실행">nohup과 결합하여 긴 프로세스를 실행</a></li> </ul> </li> <li><a href="#_함정과_일반적인_오류">함정과 일반적인 오류</a> <ul class="sectlevel2"> <li><a href="#_ctrlz와_ctrlc를_혼동하다">Ctrl+Z와 Ctrl+C를 혼동하다</a></li> <li><a href="#_작업은_셸에_국한됩니다">작업은 셸에 국한됩니다.</a></li> <li><a href="#_작업은_셸이_닫히면_생존하지_못합니다">작업은 셸이 닫히면 생존하지 못합니다.</a></li> <li><a href="#_대화형_프로세스와_fg">대화형 프로세스와 fg</a></li> </ul> </li> <li><a href="#_요약_다이어그램">요약 다이어그램</a></li> <li><a href="#_왜_fg가_과소평가되는가">왜 fg가 과소평가되는가?</a></li> <li><a href="#_기술_메모리_신호">기술 메모리 : 신호</a></li> <li><a href="#_결론">결론</a></li> <li><a href="#_참고문헌">참고문헌</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽기 시간 : 10 minutes</div> <p>당신은 던집니다`./gradlew build`, 터미널이 3분 동안 차단되며, 다른 일을 해야 <em>대기 중</em> 인가요? 새 탭을 열 필요가 없습니다.`Ctrl+Z`프로세스를 일시 중지하고,`fg`그곳으로 정확히 데려다 놓습니다. 이는 개발자의 일상에서 가장 과소평가되는 유닉스 팁입니다.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">틱</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_문제_바쁜_터미널">문제 : 바쁜 터미널</h2> <div class="sectionbody"> <div class="paragraph"> <p>모든 개발자는 이런 상황을 겪었습니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew build > Building...</code></pre> </div> </div> <div class="paragraph"> <p>터미널이 잠겼습니다. 더 이상 명령을 입력할 수 없습니다. 파일을 확인하고 실행해야 할`git status`, 또는 점유된 포트를 확인하세요.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "터미널" as term participant "Gradle (프로세스)" as gradle dev -> term : ./gradlew build term -> gradle : Lance le build gradle -> term : Occupe le terminal\n(pas de prompt) dev -> term : veut taper une commande term --> dev : ❌ Terminal bloqué note right of dev Le développeur est paralysé pendant toute la durée du build end note @enduml</pre> </div> </div> <div class="paragraph"> <p>대부분의 개발자들은 새로운 터미널을 엽니다. 하지만 더 우아하고, 더 빠르고, 네이티브한 해결책이 있습니다: 작업 관리</p> </div> </div> </div> <div class="sect1"> <h2 id="_세_가지_필수_명령어">세 가지 필수 명령어</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_ctrlz_일시_중지_sigtstp">Ctrl+Z — 일시 중지 (SIGTSTP)</h3> <div class="paragraph"> <p>`Ctrl+Z`신호를 보냅니다`SIGTSTP`포그라운드 프로세스에. 프로세스는<strong>중단된</strong>— 죽지 않은 — 그리고 터미널이 프롬프트를 되찾는다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew build > Building... ^Z [1]+ Stoppé ./gradlew build $</code></pre> </div> </div> <div class="paragraph"> <p>대괄호 안의 숫자`[1]`(two spaces)<strong>잡 번호</strong>. Le `+`기본 작업을 나타냅니다.</p> </div> </div> <div class="sect2"> <h3 id="_fg_앞으로_가져오기">fg — 앞으로 가져오기</h3> <div class="paragraph"> <p>`fg`일시 정지된 작업을 포그라운드로 가져옵니다. 프로세스는 정확히 중지된 지점에서 다시 시작됩니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ fg ./gradlew build > Building... (reprend où il en était)</code></pre> </div> </div> <div class="paragraph"> <p>특정 작업 번호:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ fg %2</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_bg_백그라운드에서_재개">bg — 백그라운드에서 재개</h3> <div class="paragraph"> <p>`bg`프로세스를 <em>sans</em> 블로킹하지 않고 계속 진행하세요. 긴 빌드에 적합합니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ bg [1]+ ./gradlew build & $</code></pre> </div> </div> <div class="paragraph"> <p>Le `&`마지막에 그것은 프로세스가 백그라운드에서 실행 중임을 의미합니다.</p> </div> </div> <div class="sect2"> <h3 id="_jobs_셸의_작업_목록_보기">jobs — 셸의 작업 목록 보기</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ jobs [1]- Stoppé vim README.md [2]+ En cours ./gradlew build</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif state "전경\n(차단된 터미널)" as fg #LightCoral state "일시 중지됨\n(Ctrl+Z)" as stopped #LightYellow state "배경\n(bg)" as bg_ #LightGreen [*] --> fg : Lance une commande fg --> stopped : Ctrl+Z\n(SIGTSTP) stopped --> fg : fg\nreprend en avant-plan stopped --> bg_ : bg\nreprend en arrière-plan bg_ --> fg : fg\nramène en avant-plan fg --> [*] : Commande terminée note right of stopped Le processus est figé mais _pas_ tué end note note left of bg_ Le terminal est libre le build continue end note @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_시나리오_1_긴_빌드">시나리오 1 : 긴 빌드</h2> <div class="sectionbody"> <div class="paragraph"> <p>이는 가장 일반적인 사용 사례입니다. Gradle 빌드를 실행하면 터미널이 막히고 다른 작업을 해야 합니다.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE autonumber actor Développeur as dev participant "터미널" as term participant "Gradle" as gradle database "상태\n프로세스" as state dev -> term : ./gradlew build term -> gradle : Lance le build gradle -> state : En cours (FG) dev -> term : Ctrl+Z term -> state : Suspendu (job [1]) term --> dev : Prompt libre $ dev -> term : git status term --> dev : working tree clean dev -> term : fg term -> state : Reprend (FG) gradle --> dev : Build réussi ✓ note right of state Le processus Gradle n'a jamais été tué Il reprend exactement où il s'était arrêté end note @enduml</pre> </div> </div> <div class="sect2"> <h3 id="_한_걸음씩">한 걸음씩</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew build > Building... ^Z [1]+ Stoppé ./gradlew build $ git status On branch main nothing to commit, working tree clean $ fg ./gradlew build > Building... BUILD SUCCESSFUL in 2m 34s</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_시나리오_2_잊어버린_편집자">시나리오 2 : 잊어버린 편집자</h2> <div class="sectionbody"> <div class="paragraph"> <p>당신은 안에 있습니다`vim`, 다른 파일을 <em>sans</em> 떠나지 않고 확인해야 합니다`vim`.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Dans vim, en mode commande : :shell $ cat /path/to/other/file.txt $ exit # Retour dans vim</code></pre> </div> </div> <div class="paragraph"> <p>하지만 그것은 무겁다. 그리고`Ctrl+Z`, 즉시적입니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Dans vim, n'importe quel moment : Ctrl+Z [1]+ Stoppé vim README.md $ cat /path/to/other/file.txt # ... lire le fichier ... $ fg vim README.md # Retour exact là où on en était, curseur en place</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE autonumber actor Développeur as dev participant "vim" as vim participant "껍질" as shell dev -> vim : édition en cours dev -> vim : Ctrl+Z vim -> shell : Suspendu (job [1]) dev -> shell : cat autre_fichier.txt shell --> dev : contenu du fichier dev -> shell : fg shell -> vim : Reprend (job [1]) vim --> dev : Curseur exactement\nà la même position note right of vim vim restaure intégralement l'état : position du curseur, buffer, undo stack end note @enduml</pre> </div> </div> <div class="paragraph"> <p>참고:`vim`완벽하게 그 상태를 복구한 후`fg`: 커서 위치, 버퍼 내용, 실행 취소 기록 — 전부 보존됩니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_시나리오_3_opencode_프로세스가_일시_중지됨">시나리오 3: opencode 프로세스가 일시 중지됨</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 기사를 쓰게 된 계기는 이 시나리오입니다. 당신은 사용하고 있습니다.<code>opencode</code>(코드에서 LLM을 실행하기 위한 CLI 툴), 그리고 프로세스가 중지됩니다.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif skinparam componentStyle rectangle actor Développeur as dev participant "opencode (LLM 에이전트)" as agent participant "껍질" as shell participant "깃" as git dev -> agent : Session active agent -> agent : Tour de parole\ndu LLM en cours note over agent Ctrl+Z arrive en plein milieu d'une analyse de code end note dev -> agent : Ctrl+Z agent -> shell : Suspendu (job [1]) dev -> git : git diff git --> dev : changements visibles dev -> shell : fg shell -> agent : Reprend (job [1]) agent --> dev : Reprend exactement\nl'analyse en cours note right of agent Aucune perte de contexte Le LLM reprend sa réponse exactement où il en était end note @enduml</pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ opencode # ... session en cours, LLM analyse le code ... ^Z [1]+ Stoppé opencode $ git diff HEAD~1 # vérifier les changements récents $ fg opencode # Le LLM reprend là où il s'était arrêté</code></pre> </div> </div> <div class="paragraph"> <p>장점은 두 배입니다:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>컨텍스트 손실 없음</strong>: LLM 세션, 대화 기록, 열린 파일 — 모든 것이 보존됩니다</p> </li> <li> <p><strong>재시작 없음</strong>opencode를 재시작할 필요 없고, 컨텍스트를 재로드할 필요 없고, LLM에게 문제를 다시 설명할 필요 없어</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_시나리오_4_여러_작업을_동시에_관리하기">시나리오 4 : 여러 작업을 동시에 관리하기</h2> <div class="sectionbody"> <div class="paragraph"> <p><code>fg</code> et `bg`여러 개가 일시 중지된 상태에서 특정 프로세스를 대상으로 작업 번호를 받아들입니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ vim config.yml ^Z [1]+ Stoppé vim config.yml $ ./gradlew test ^Z [2]+ Stoppé ./gradlew test $ htop ^Z [3]+ Stoppé htop $ jobs [1] Stoppé vim config.yml [2]- Stoppé ./gradlew test [3]+ Stoppé htop $ fg %2 ./gradlew test # Le build reprend en avant-plan $ bg %3 [3] htop & # htop reprend en arrière-plan</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE rectangle "중지된 작업" as jobs #LightYellow { card "[1] vim config.yml" as j1 card "[2] ./gradlew test" as j2 card "[3] htop" as j3 } rectangle "행동" as actions #LightGreen { card "fg %2 → 전경" as a1 card "bg %3\n→ 배경" as a2 card "fg %1 → 전경" as a3 } jobs --> actions : fg/bg + numéro de job actions --> j2 : Reprend actions --> j3 : En arrière-plan note bottom of jobs Chaque job conserve son état exact entre les suspend/resume end note @enduml</pre> </div> </div> <div class="sect2"> <h3 id="_작업_명령어_요약">작업 명령어 요약</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 20%;"> <col style="width: 40%;"> <col style="width: 40%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">주문</th> <th class="tableblock halign-left valign-top">효과</th> <th class="tableblock halign-left valign-top">예시</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+Z</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">전경 프로세스를 일시 중지합니다</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">전송`SIGTSTP`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>fg</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">기본 작업을 포그라운드에서 재개합니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>fg</code> ou <code>fg %1</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>fg %n</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">작업 n을 전경에서 재개</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>fg %2</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>bg</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">백그라운드에서 기본 작업 재개</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>bg</code> ou <code>bg %1</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>bg %n</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">백그라운드에서 작업 n을 다시 시작</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>bg %2</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>jobs</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">현재 쉘의 작업 목록을 나열</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>jobs -l</code>(PID와 함께)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>kill %n</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">작업 n 종료</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>kill %2</code></p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_fg_bg_ctrlz_ctrlc_및_의_차이">fg, bg, Ctrl+Z, Ctrl+C 및 &의 차이</h2> <div class="sectionbody"> <div class="paragraph"> <p>많은 개발자들이 이러한 메커니즘을 혼동합니다. 이것이 결정적인 명확화입니다.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif rectangle "**Ctrl+Z**\nSIGTSTP" as ctrlz #LightYellow { card "프로세스를 일시 중지 (메모리에 여전히 존재) fg/bg와 함께 사용 가능" as c1 } rectangle "**Ctrl+C**\nSIGINT" as ctrlc #LightCoral { card "프로세스를 죽여 (돌아갈 수 없습니다) 상태 전체 손실" as c2 } rectangle "**& **\n(배경)" as ampersand #LightGreen { card "직접 실행 백그라운드에서 터미널을 즉시 자유롭게" as c3 } rectangle "**fg** (전경)" as fg_ #SkyBlue { card "일시 정지된 작업을 전경으로 가져와 터미널이 사용 중" as c4 } rectangle "**bg**\n(배경)" as bg_ #Lavender { card "작업을 재개합니다\n백그라운드에서 일시 중지된\n터미널 사용 가능" as c5 } ctrlz -right-> fg_ : fg pour reprendre ctrlz -right-> bg_ : bg pour continuer\nen arrière-plan ctrlc -right-> c2 : Pas de retour\nprocessus tué note bottom of ctrlz Le processus est **figé** mais **pas tué** end note note bottom of ampersand Alternative : lancer ./gradlew build & directement en arrière-plan end note @enduml</pre> </div> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 16.6666%;"> <col style="width: 33.3333%;"> <col style="width: 16.6666%;"> <col style="width: 33.3335%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">단축키/명령</th> <th class="tableblock halign-left valign-top">신호</th> <th class="tableblock halign-left valign-top">효과</th> <th class="tableblock halign-left valign-top">뒤로 가시겠어요?</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+Z</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGTSTP</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">프로세스를 일시 중지 (메모리 내에 고정된, 동결된)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">네 :`fg` ou <code>bg</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+C</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGINT</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">프로세스를 죽이세요 (완료됨)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">아니요 : 파괴된 프로세스</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+\</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGQUIT</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">프로세스를 죽이고 + 코어 덤프</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">아니요: 프로세스가 파괴되었습니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>commande &</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">백그라운드에서 바로 실행</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`fg`앞으로 가져오기 위해</p></td> </tr> </tbody> </table> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <code>Ctrl+Z`이다<strong>비파괴적</strong>. 프로세스는 그대로 메모리에서 정지됩니다. 당신은 즉시 이어서 할 수 있습니다.`fg</code>. 이것은 _pause_일 뿐, _stop_이 아닙니다. </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_작업의_전체_수명_주기">작업의 전체 수명 주기</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif title 셸 작업의 전체 생명 주기 state "존재하지 않는" as none state "전경 (터미널 점유 중)" as foreground #LightCoral state "일시 정지됨 (Ctrl+Z / SIGTSTP)" as suspended #LightYellow state "배경\n(bg ou &)" as background #LightGreen state "완료 (exit code 0)" as done #LightGray [*] --> none none --> foreground : tape une commande foreground --> suspended : Ctrl+Z foreground --> done : fin normale suspended --> foreground : fg suspended --> background : bg suspended --> done : kill %n background --> foreground : fg background --> done : fin normale\n(en arrière-plan) background --> suspended : Ctrl+Z\n(si fg puis Ctrl+Z) done --> [*] note right of suspended L'état suspendu est le pivot de tout le système de jobs end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_고급_팁">고급 팁</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_fg와_가장_최근의_직업_및_교대">fg와 가장 최근의 직업 및 교대</h3> <div class="paragraph"> <p><code>fg`인수 없이 표시된 작업을 되돌린다.</code>+<code>(가장 최신). 하지만 또한 사용할 수 있습니다</code>%-`이전 작업을 대상으로 지정하려면 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ vim file1.txt ^Z [1]+ Stoppé vim file1.txt $ vim file2.txt ^Z [2]+ Stoppé vim file2.txt $ fg # ramène job [2] (le plus récent) $ fg %- # ramène job [1] (le précédent)</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_작업을_깔끔하게_종료하다">작업을 깔끔하게 종료하다</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ jobs [1]- Stoppé vim config.yml [2]+ Stoppé ./gradlew test $ kill %2 # envoie SIGTERM au job 2 $ kill -9 %1 # envoie SIGKILL au job 1 (force)</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_disown_쉘에서_분리">disown : 쉘에서 분리</h3> <div class="paragraph"> <p><code>disown`쉘의 작업 테이블에서 작업을 제거합니다. 프로세스는 계속 실행되지만 더 이상 불러올 수 없습니다.`fg</code>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew build & [1] 12345 $ disown %1 # Le processus continue mais n'est plus lié au shell # Ça survives à la fermeture du terminal</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_nohup과_결합하여_긴_프로세스를_실행">nohup과 결합하여 긴 프로세스를 실행</h3> <div class="paragraph"> <p>터미널이 종료될 때 프로세스가 살아남게 하려면 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ nohup ./gradlew build & [1] 12345 $ disown %1 # Le build continue même si vous fermez le terminal</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif rectangle "fg" as fg_ #SkyBlue { card "일을 가져와라\n가장 최근의 (+)" as f1 card "특정 직업 대상 특정 : fg %n" as f2 card "교대로 : fg %-" as f3 } rectangle "kill %n" as kill_ #LightCoral { card "SIGTERM (정상)" as k1 card "SIGKILL -9 (강제)" as k2 } rectangle "거부하다" as disown #Lavender { card "쉘에서 분리 (연결 해제 후에도 살아남음)" as d1 } rectangle "nohup + &" as nohup_ #LightGreen { card "면역된 프로세스 SIGHUP에 대한 (터미널 종료 시 살아남음 터미널)" as n1 } fg_ -right-> kill_ : si faut\nterminer kill_ -right-> disown_ : ou détacher nohup_ -left-> fg_ : fg ramène en\navant-plan note bottom of disown_ Après disown, fg ne peut plus ramener le job end note @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_함정과_일반적인_오류">함정과 일반적인 오류</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_ctrlz와_ctrlc를_혼동하다">Ctrl+Z와 Ctrl+C를 혼동하다</h3> <div class="paragraph"> <p>가장 흔한 실수입니다.`Ctrl+C`프로세스를 죽입니다.`Ctrl+Z`그를 중단합니다. 만약 당신이 누르면`Ctrl+C`반사적으로, 전체 상태가 손실됩니다 — 열린 파일, LLM 세션, 진행 중인 빌드.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE rectangle "Ctrl+Z (SIGTSTP)" as z #LightGreen { card "메모리에서 고정된 프로세스" as z1 card "fg 그를 무사히 데려온다" as z2 card "손실 없음" as z3 } rectangle "Ctrl+C (SIGINT)" as c #LightCoral { card "프로세스 완료" as c1 card "영구적으로 손실된 상태" as c2 card "돌이킬 수 없습니다" as c3 } note bottom of z Pause → Reprendre end note note bottom of c Kill → Perdu end note @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_작업은_셸에_국한됩니다">작업은 셸에 국한됩니다.</h3> <div class="paragraph"> <p><code>jobs</code>, <code>fg</code> et `bg`다른 터미널을 열면 다른 터미널의 작업을 볼 수 없습니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Terminal 1 $ vim file.txt ^Z [1]+ Stoppé vim file.txt # Terminal 2 (nouveau) $ jobs # (rien — les jobs sont locaux au shell)</code></pre> </div> </div> <div class="paragraph"> <p>시스템 전체 프로세스를 보려면`ps` ou <code>htop</code>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">ps aux | grep vim</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_작업은_셸이_닫히면_생존하지_못합니다">작업은 셸이 닫히면 생존하지 못합니다.</h3> <div class="paragraph"> <p>터미널을 닫으면 일시 중지된 작업 또는 백그라운드 작업이 모두 삭제됩니다. 프로세스가 살아남으려면 사용`nohup`+<code>disown</code>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ nohup ./gradlew build & [1] 12345 $ disown %1 # Fermer le terminal → le build continue</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_대화형_프로세스와_fg">대화형 프로세스와 fg</h3> <div class="paragraph"> <p>일부 대화형 프로그램은 한 이후에 잘 작동하지 않는다`Ctrl+Z`+<code>fg</code>. 드문하지만 발생한다 :</p> </div> <div class="ulist"> <ul> <li> <p>신호를 사용하는 일부 프로그램(vim, htop, less)은 잘 처리합니다.<code>Ctrl+Z</code>)</p> </li> <li> <p>장시간 실행되는 네트워크 프로그램(ssh, opencode)은 일반적으로 정상적으로 복구됩니다.</p> </li> <li> <p>터미널을 수정하는 프로그램(ncurses)은 때때로 터미널을 예기치 않은 상태로 남겨둘 수 있다</p> </li> </ul> </div> <div class="paragraph"> <p>터미널이 손상된 후`fg`, 입력 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">reset</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_요약_다이어그램">요약 다이어그램</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif skinparam ArrowColor #444444 title "fg — 모든 것을 바꾸는 팁" rectangle "문제" as problem #LightCoral { card "터미널 차단됨\n프로세스에 의해" as p1 card "새로운\n터미널 열기 = 무거운 해결책" as p2 } rectangle "**해결책**" as solution #LightGreen { card "Ctrl+Z → 일시 정지" as s1 card "fg → 다시 이어간다" as s2 card "배경에서" as s3 card "jobs → 정지된 것 보기" as s4 } rectangle "장점" as advantages #SkyBlue { card "맥락 손실 없음" as a1 card "재시작하지 마세요" as a2 card "터미널 하나면 충분합니다." as a3 } problem -right-> solution : "네이티브 솔루션 40년 된 유닉스" solution -right-> advantages : "결과" note bottom of advantages fg n'est pas un tips obscur C'est un mécanisme fondamental du shell Unix end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_왜_fg가_과소평가되는가">왜 fg가 과소평가되는가?</h2> <div class="sectionbody"> <div class="paragraph"> <p>대부분의 현대 개발자들은 발견합니다`fg`늦거나, 전혀 이루어지지 않을 수도 있습니다. 몇 가지 이유 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>IDE는 터미널을 숨깁니다.</strong>: VS Code는 내장 터미널을 제공하지만, 여러 탭이`fg`겉으로는 덜 필요함</p> </li> <li> <p><strong>그래픽 도구가 CLI를 대체합니다</strong>: 파일 관리자, 시스템 모니터, 그래픽 Git 클라이언트</p> </li> <li> <p><strong>tmux와 스크린</strong>: 이 멀티플렉서는 같은 문제를 다르게 해결하지만`fg`더 간단하고 항상 사용 가능합니다</p> </li> </ol> </div> <div class="paragraph"> <p>그런데,`fg`는 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>보편적인</strong>POSIX 셸 모두에 존재 (bash, zsh, fish…​)</p> </li> <li> <p><strong>의존 없이</strong>tmux 또는 screen을 설치할 필요가 없습니다</p> </li> <li> <p><strong>스냅샷</strong>: 두 번의 타격 (<code>Ctrl+Z`그리고`fg</code>) 일시 중지 및 재개를 위해</p> </li> <li> <p><strong>컨텍스트 보존자</strong>: 프로세스의 상태는 무결합니다</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif rectangle "왜 fg가 과소 평가됩니까?" as why #LightCoral { card "IDE와 터미널 다중 탭" as w1 card "그래픽 도구\nCLI를 대체하는" as w2 card "tmux/screen 문제를 해결합니다 다른 방식으로" as w3 } rectangle "왜 fg 이다\n더 우월한 ?" as superior #LightGreen { card "범용: bash, zsh, fish, sh..." as s1 card "의존성 없음: 설치 필요 없음" as s2 card "두 번의 타격:\nCtrl+Z 그리고 fg" as s3 card "보존된 컨텍스트 :\n상태 손실 없음" as s4 } why -right-> superior : "간단함 항상 이긴다" @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_기술_메모리_신호">기술 메모리 : 신호</h2> <div class="sectionbody"> <div class="paragraph"> <p>호기심을 가진 사람들을 위해, 관련된 신호는 다음과 같습니다:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 14.2857%;"> <col style="width: 28.5714%;"> <col style="width: 28.5714%;"> <col style="width: 28.5715%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">신호</th> <th class="tableblock halign-left valign-top">이름</th> <th class="tableblock halign-left valign-top">보낸 사람</th> <th class="tableblock halign-left valign-top">효과</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGINT</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+C</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">중단 — 프로세스를 종료합니다</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGQUIT</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+\</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">코어 덤프와 함께 종료</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">18</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGTSTP</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+Z</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">대화형 정지 — 프로세스 일시 정지</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">19</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGCONT</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>fg</code>/<code>bg</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">계속 — 일시 중지된 프로세스를 재개한다</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">15</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGTERM</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>kill %n</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">깨끗한 종료</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">9</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGKILL</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>kill -9 %n</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">강제 종료 (차단할 수 없음)</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>전체 흐름 :</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif participant "사용자" as user participant "쉘" as shell participant "프로세스" as proc user -> shell : Ctrl+Z shell -> proc : SIGTSTP (signal 18) note right of proc : Processus figé\nen mémoire user -> shell : fg shell -> proc : SIGCONT (signal 19) note right of proc : Processus reprend\nen avant-plan user -> shell : bg shell -> proc : SIGCONT (signal 19) note right of proc : Processus reprend\nen arrière-plan user -> shell : Ctrl+C shell -> proc : SIGINT (signal 2) note right of proc : Processus terminé\nétat perdu @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_결론">결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>`fg`이것은 obscure한 팁이 아니라, 1970년대부터 사용 가능한 Unix 셸의 기본 메커니즘입니다. 대부분의 개발자들이 이를 모른다는 사실은 우리의 시대를 보여주는 증상입니다: IDE와 멀티플렉서가 우리에게 기본으로부터 멀어지게 만들었습니다.</p> </div> <div class="paragraph"> <p>하지만 SSH 서버에 접속해 있거나, 최소한의 터미널을 사용 중이거나, 단순히 사용 중인 경우`opencode`그리고 LLM은 한창 작업 중입니다 —<code>Ctrl+Z</code>, <code>fg</code>, <code>bg</code>, `jobs`votre 가장 친한 친구들이에요.</p> </div> <div class="paragraph"> <p><em><em>_ Ctrl+Z 일시정지, fg 재개. 터미널의 일시정지-재생입니다. </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_참고문헌">참고문헌</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><code>man bash</code>— 섹션 JOB CONTROL</p> </li> <li> <p><code>man signal</code>— POSIX 신호 목록</p> </li> <li> <p><a href="https://www.gnu.org/software/bash/manual/bash.html#Job-Control">Bash 참조 매뉴얼 — 작업 제어</a></p> </li> <li> <p><a href="https://man7.org/linux/man-pages/man7/signal.7.html">man 7 signal — 리눅스 신호</a></p> </li> <li> <p><a href="https://tldp.org/LDP/abs/html/x312743.htm">고급 Bash 스크립팅 가이드 — 작업 제어</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0103_vscode_local_install_custom_fonts_post.html Fri, 17 Apr 2026 00:00:00 +0000 blog/2026/0103_vscode_local_install_custom_fonts_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_과정_개요">과정 개요</a></li> <li><a href="#_왜냐하면_홈에서_vs_code">왜냐하면: 홈에서 VS Code</a> <ul class="sectlevel2"> <li><a href="#_시스템_설치의_문제">시스템 설치의 문제</a></li> <li><a href="#_해결책_로컬_설치">해결책: 로컬 설치</a></li> <li><a href="#_실질적인_이점">실질적인 이점</a></li> </ul> </li> <li><a href="#_메인_메뉴_글꼴_사용자_정의">메인 메뉴 글꼴 사용자 정의</a> <ul class="sectlevel2"> <li><a href="#_확인">확인</a></li> <li><a href="#_기법_직접_css_패치">기법: 직접 CSS 패치</a></li> <li><a href="#_무결성_경고_삭제">무결성 경고 삭제</a></li> </ul> </li> <li><a href="#_탐색기_창의_글꼴_사용자_지정_전투">탐색기 창의 글꼴 사용자 지정 — 전투</a> <ul class="sectlevel2"> <li><a href="#_시도_1_존재하지_않는_매개변수">시도 1: 존재하지 않는 매개변수</a></li> <li><a href="#_시도_2_custom_css_and_js_loader_확장_프로그램">시도 2: Custom CSS and JS Loader 확장 프로그램</a></li> <li><a href="#_함정_확장_기능을_매번_활성화해야_합니다">함정 : 확장 기능을 매번 활성화해야 합니다.</a></li> <li><a href="#_시도_3_선들이_겹칩니다">시도 3 : 선들이 겹칩니다.</a></li> <li><a href="#_해결_방법_zoom_상위_컨테이너에">해결 방법: <code>zoom</code> 상위 컨테이너에</a></li> <li><a href="#_선택기의_요약_및_작동하는_것">선택기의 요약 및 작동하는 것</a></li> </ul> </li> <li><a href="#_자동_업데이트_스크립트">자동 업데이트 스크립트</a> <ul class="sectlevel2"> <li><a href="#_문제">문제</a></li> <li><a href="#_스크립트_vscode_update_sh">스크립트 `vscode-update.sh</a></li> </ul> </li> <li><a href="#_관련_파일_개요">관련 파일 — 개요</a></li> <li><a href="#_배운_교훈">배운 교훈</a> <ul class="sectlevel2"> <li><a href="#_홈에_설치하면_모든_것이_해제됩니다">홈에 설치하면 모든 것이 해제됩니다</a></li> <li><a href="#_zoom_font_size_목록_컴포넌트에_대해">zoom` > <code>font-size</code> 목록 컴포넌트에 대해</a></li> <li><a href="#_custom_css_확장은_명시적_활성화가_필요합니다">Custom CSS 확장은 명시적 활성화가 필요합니다.</a></li> <li><a href="#_업데이트_스크립트는_필수적입니다">업데이트 스크립트는 필수적입니다.</a></li> </ul> </li> <li><a href="#_빠른_참조">빠른 참조</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽는 시간 : 8 minutes</div> <p>왜 VS Code를 설치하나요?<code>/opt`또는 통해`apt`당신이 그것을 홈에 놓을 수 있고 IDE를 놀이터로 바꾼 뒤에도 절대 타이핑하지 않을 때`sudo</code>?여기서는 로컬 설치의 이야기와 메뉴와 파일 탐색기의 글꼴을 확대하기 위한 치열한 싸움이 이어집니다.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">똑</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_과정_개요">과정 개요</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle actor Développeur as dev actor "python print("opencode\n+ LLM")" as agent package "홈 사용자(~)" #LightGreen { package "~/apps/" { component "VS Code\n(tarball)" as vscode #SkyBlue component "vscode-update.sh" as script #LightYellow } package "~/.config/Code/" { component "settings.json" as settings #Lavender } package "~/.vscode-custom-css/" { component "custom.css (zoom: 1.25)" as customcss #Lavender } } cloud "code.visualstudio.com" as download dev --> vscode : Télécharge & installe dev --> script : Lance mise à jour script --> download : wget dernière version script --> vscode : Remplace + re-patch CSS agent --> settings : Écrit config agent --> customcss : Écrit zoom CSS agent --> vscode : Patch workbench CSS note right of vscode Installation dans le home = contrôle total sans sudo end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_왜냐하면_홈에서_vs_code">왜냐하면: 홈에서 VS Code</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_시스템_설치의_문제">시스템 설치의 문제</h3> <div class="paragraph"> <p>VS Code를 통해 설치된`apt`, <code>dnf`또는 안에서</code>/opt`앱 파일을 루트 권한 뒤에 잠급니다. 네이티브 CSS의 모든 수정, de`product.json`또는 설치 폴더가 필요합니다`sudo`.</p> </div> <div class="paragraph"> <p>그런데 사용할 때<strong>오픈코드</strong>(tool CLI를 사용하여 자신의 코드에서 LLM을 조종), 에이전트는 할 수 있어야 :</p> </div> <div class="ulist"> <ul> <li> <p>설정 파일에 쓰기`~/.config/Code/User/settings.json`) — 이건 이미 홈에 있습니다</p> </li> <li> <p>IDE 에셋을 수정하세요 (워크벤치 CSS,<code>product.json</code>) 고급 커스터마이징을 위해 — 그건 sudo 없이 잠겨 있습니다.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_해결책_로컬_설치">해결책: 로컬 설치</h3> <div class="paragraph"> <p>공식 tarball 아카이브를 다운로드하고 바로 거기에 압축을 풉니다.<code>~/apps/</code>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">mkdir -p ~/apps cd ~/apps wget "https://code.visualstudio.com/sha/download?build=stable&os=linux-x64" -O vscode.tar.gz tar -xzf vscode.tar.gz rm vscode.tar.gz</code></pre> </div> </div> <div class="paragraph"> <p>그렇다면 이진 파일은`~/apps/VSCode-linux-x64/bin/code`. 아무것도`sudo`아래의 어떤 파일을 읽거나 수정하거나 교체하는 데 필요하지 않습니다`~/apps/VSCode-linux-x64/`.</p> </div> </div> <div class="sect2"> <h3 id="_실질적인_이점">실질적인 이점</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE rectangle "시스템 설치 (/opt, apt, dnf)" #LightCoral { card "VS Code의 루트 속성" { [CSS du workbench : sudo requis] [product.json : sudo requis] [Dossier d'install : non modifiable] } } rectangle "설치 홈\n(~/apps)" #LightGreen { card "VS Code 사용자 속성" { [CSS du workbench : libre] [product.json : libre] [Dossier d'install : libre] [Script update maison] } } "시스템 설치 (/opt, apt, dnf)" -right-> "설치 홈\n(~/apps)" : **Non, merci**\nJe prends le home note bottom of "설치 홈\n(~/apps)" L'agent opencode+LLM peut modifier les fichiers de l'IDE sans aucune élévation de privilèges end note @enduml</pre> </div> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 66.6667%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">장점</th> <th class="tableblock halign-left valign-top">세부</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">sudo 없음</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">IDE의 모든 파일은 사용자에게 속합니다</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">CSS 직접 수정</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">패치할 수 있다.`workbench.desktop.main.css`특권 상승 없이</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">집에서 만든 업데이트 스크립트</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">간단한 셸 스크립트가 자동으로 다운로드하고, 대체하고, 재패치합니다</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">고립</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">시스템 설치는 오염되지 않았습니다; 롤백 = 폴더 삭제</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_메인_메뉴_글꼴_사용자_정의">메인 메뉴 글꼴 사용자 정의</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_확인">확인</h3> <div class="paragraph"> <p>메인 메뉴(File, Edit, View…​)와 드롭다운의 기본 폰트가 너무 작습니다. VS Code에는 이를 변경할 수 있는 설정 옵션이 없습니다.</p> </div> </div> <div class="sect2"> <h3 id="_기법_직접_css_패치">기법: 직접 CSS 패치</h3> <div class="paragraph"> <p>파일 끝에 CSS를 추가합니다.<code>workbench.desktop.main.css</code>(Empty)</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE autonumber actor Développeur as dev participant "workbench.desktop\n.main.css" as css participant "product.json" as product participant "VS Code" as vscode == Patch CSS == dev -> css : Ajouter règles font-size\n(.menubar-menu-title, etc.) dev -> vscode : Redémarrer VS Code vscode -> vscode : Charge le CSS patché vscode --> dev : Menus et dropdowns en 23px/22px ✓ == Suppression warning == vscode --> dev : ⚠️ "당신의 설치는 손상되었습니다." dev -> product : Supprimer clé "체크섬"\n(python3 -c ...) dev -> vscode : Redémarrer VS Code vscode --> dev : Plus de warning ✓ note over css, product Deux fichiers dans ~/apps/ = modifiables sans sudo end note @enduml</pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">CSS_FILE="$HOME/apps/VSCode-linux-x64/resources/app/out/vs/workbench/workbench.desktop.main.css" cat >> "$CSS_FILE" << 'EOF' .menubar-menu-title{font-size:23px!important} .menubar>.menubar-menu-button{font-size:23px!important} .monaco-menu-option{font-size:22px!important;line-height:34px!important} .monaco-menu .action-label:not(.codicon){font-size:22px!important} .menubar-menu-items-holder .monaco-menu .action-item .action-label{font-size:22px!important} EOF</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_무결성_경고_삭제">무결성 경고 삭제</h3> <div class="paragraph"> <p>VS Code는 자신의 파일 변경을 감지하고 "Your installation is corrupt" 배너를 표시합니다. 이를 방지하기 위해 체크섬을 삭제합니다.<code>product.json</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-python hljs" data-lang="python">import json product_json = "$HOME/apps/VSCode-linux-x64/resources/app/product.json" with open(product_json, 'r') as f: data = json.load(f) data.pop('checksums', None) with open(product_json, 'w') as f: json.dump(data, f, indent=2)</code></pre> </div> </div> <div class="paragraph"> <p>재시작 후, 경고가 더 이상 없고 메뉴가 finally 읽을 수 있습니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_탐색기_창의_글꼴_사용자_지정_전투">탐색기 창의 글꼴 사용자 지정 — 전투</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_시도_1_존재하지_않는_매개변수">시도 1: 존재하지 않는 매개변수</h3> <div class="paragraph"> <p>먼저 네이티브 매개변수를 시도합니다.<code>workbench.tree.fontSize`안에`settings.json</code>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{ "workbench.tree.fontSize": 20 }</code></pre> </div> </div> <div class="paragraph"> <p>결과 :<strong>효과 없음</strong>. 이 설정은 VS Code에 존재하지 않습니다. 인식되지 않는 설정은 조용히 무시된다는 증거.</p> </div> </div> <div class="sect2"> <h3 id="_시도_2_custom_css_and_js_loader_확장_프로그램">시도 2: Custom CSS and JS Loader 확장 프로그램</h3> <div class="paragraph"> <p>확장을 설치합니다`be5invis.vscode-custom-css`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">~/apps/VSCode-linux-x64/bin/code --install-extension be5invis.vscode-custom-css</code></pre> </div> </div> <div class="paragraph"> <p>CSS 파일을 만든다`~/.vscode-custom-css/custom.css`탐색기 요소들을 대상으로 하는 선택자와 함께 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">.monaco-tree-rows .monaco-tree-row, .sidebar .monaco-list-row, .explorer-viewlet .monaco-list-row, .monaco-list-row .monaco-icon-label { font-size: 22px !important; line-height: 36px !important; }</code></pre> </div> </div> <div class="paragraph"> <p>그리고 우리는 이 파일을 설정에서 참조합니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{ "vscode_custom_css.imports": [ "file:///home/user/.vscode-custom-css/custom.css" ] }</code></pre> </div> </div> <div class="paragraph"> <p>결과 :<strong>변경 사항이 적용되지 않습니다.</strong>.</p> </div> </div> <div class="sect2"> <h3 id="_함정_확장_기능을_매번_활성화해야_합니다">함정 : 확장 기능을 매번 활성화해야 합니다.</h3> <div class="paragraph"> <p>확장 문서는 이 중요한 점에 대해 언급하지 않습니다: 커스텀 CSS를 수정할 때마다<strong>반드시</strong>팔레트에서 명령을 실행하세요 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><code>Ctrl+Shift+P</code>→ 타자치다<strong>사용자 정의 CSS 및 JS 활성화</strong></p> </li> <li> <p>VS Code가 재시작을 요청합니다 → 수락</p> </li> </ol> </div> <div class="paragraph"> <p>이 단계가 없으면 CSS는 IDE에 절대 주입되지 않습니다.</p> </div> </div> <div class="sect2"> <h3 id="_시도_3_선들이_겹칩니다">시도 3 : 선들이 겹칩니다.</h3> <div class="paragraph"> <p>그리고도`font-size: 22px` et <code>line-height: 36px</code>, 내려간 글자들(g, p, f, b)이 인접한 줄을 넘어갑니다. 추가를 시도하고 있습니다`height` et <code>min-height</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">.monaco-list-row { height: 36px !important; min-height: 36px !important; }</code></pre> </div> </div> <div class="paragraph"> <p>결과 :<strong>변경 없음</strong>. VS Code는 JavaScript에서 줄 높이를 계산하고 CSS 값을 덮어씁니다.</p> </div> </div> <div class="sect2"> <h3 id="_해결_방법_zoom_상위_컨테이너에">해결 방법: <code>zoom</code> 상위 컨테이너에</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE rectangle "시도 1 존재하지 않는 매개변수" #LightCoral { card "workbench.tree.fontSize" as t1 { [VS Code ignore le paramètre] } } rectangle "시도 2 사용자 정의 CSS + font-size" #LightYellow { card ".monaco-list-row { font-size: 22px }" as t2 { [Texte plus grand\nmais lignes superposées] } } rectangle "시도 3 font-size + line-height + height" #LightYellow { card "높이: 36px !important" as t3 { [VS Code override\npar JavaScript] [Aucun effet] } } rectangle "솔루션 상위 컨테이너 줌" #LightGreen { card ".monaco-list-rows { zoom: 1.25 }" as t4 { [Texte + espacement\nproportionnels] [Layout JS respecté] [✓ Résultat conforme] } } t1 -down-> t2 : Pas de paramètre ?\nOn essaie le CSS t2 -down-> t3 : Lignes superposées ?\nOn force la hauteur t3 -down-> t4 : Override JS ?\nOn utilise zoom @enduml</pre> </div> </div> <div class="paragraph"> <p>자바스크립트 레이아웃과 싸우는 대신, 속성을 사용합니다.`zoom`줄 컨테이너에서:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">.explorer-viewlet .monaco-list-rows, .sidebar .monaco-list-rows { zoom: 1.25; }</code></pre> </div> </div> <div class="paragraph"> <p>`zoom`컨테이너 렌더링 — 텍스트와 간격 모두 — 을 균일하게 확대합니다. VS Code의 JavaScript 엔진이 계산한 레이아웃을 깨뜨리지 않으며, 비율 1.25는 대략 13px에서 16px로의 변환에 해당합니다.</p> </div> <div class="paragraph"> <p>결과 :<strong>파일 이름이 이제 가독성이 있으며, 줄이 적절히 간격되어 있습니다.</strong>.</p> </div> </div> <div class="sect2"> <h3 id="_선택기의_요약_및_작동하는_것">선택기의 요약 및 작동하는 것</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 50%;"> <col style="width: 25%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">접근</th> <th class="tableblock halign-left valign-top">CSS</th> <th class="tableblock halign-left valign-top">결과</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>font-size`위</code>.monaco-list-row`</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>font-size: 22px !important</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">더 큰 텍스트지만 겹친 줄</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>line-height</code> + <code>height`위에</code>.monaco-list-row`</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>line-height: 36px; height: 36px</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">효과 없음 (JS 오버라이드)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>zoom`위에</code>.monaco-list-rows`</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>zoom: 1.25</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">성공 — 텍스트 + 비례 간격</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_자동_업데이트_스크립트">자동 업데이트 스크립트</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE autonumber actor "개발자 또는 cron" as dev participant "vscode-update.sh" as script participant "vscode 타볼\n(code.visualstudio.com)" as remote participant "~/apps/\nVSCode-linux-x64/" as local participant "~/apps/\nvscode-backup" as backup participant "작업대\n.desktop.main.css" as css participant "product.json" as product dev -> script : ./vscode-update.sh script -> local : Lire version courante script -> remote : wget dernière version script -> script : Comparer versions alt Version identique script --> dev : "이미 최신 상태입니다!" else Nouvelle version script -> backup : Sauvegarder installation courante\n(horodatée) script -> local : rm -rf ancienne installation script -> local : mv nouvelle installation script -> css : Ajouter patch CSS\n(menubar 23px, dropdown 22px) script -> product : Supprimer checksums\n(python3) script --> dev : "업데이트 완료 1.xx.yy → 1.zz.ww" end note @enduml</pre> </div> </div> <div class="sect2"> <h3 id="_문제">문제</h3> <div class="paragraph"> <p>VS Code가 업데이트될 때, 설치 폴더를 교체하고<strong>모든 CSS 패치를 삭제하세요</strong>변경을 수동으로 매번 다시 적용해야 합니다.</p> </div> </div> <div class="sect2"> <h3 id="_스크립트_vscode_update_sh">스크립트 `vscode-update.sh</h3> <div class="paragraph"> <p>만든다`~/apps/vscode-update.sh` :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">#!/bin/bash set -e VSCODE_DIR="$HOME/apps/VSCode-linux-x64" BACKUP_DIR="$HOME/apps/vscode-backup" TEMP_DIR="/tmp/vscode-update" MENUBAR_FONT_SIZE="23px" DROPDOWN_FONT_SIZE="22px" echo "=== VS Code Local Updater ===" CURRENT_VERSION=$("$VSCODE_DIR/bin/code" --version 2>/dev/null | head -1) echo "Current version: $CURRENT_VERSION" echo "Downloading latest VS Code..." mkdir -p "$TEMP_DIR" wget -q "https://code.visualstudio.com/sha/download?build=stable&os=linux-x64" \ -O "$TEMP_DIR/vscode.tar.gz" echo "Extracting..." mkdir -p "$TEMP_DIR/extracted" tar -xzf "$TEMP_DIR/vscode.tar.gz" -C "$TEMP_DIR/extracted" NEW_VERSION=$("$TEMP_DIR/extracted/VSCode-linux-x64/bin/code" \ --version 2>/dev/null | head -1) echo "New version: $NEW_VERSION" if [ "$CURRENT_VERSION" = "$NEW_VERSION" ]; then echo "Already up to date!" rm -rf "$TEMP_DIR" exit 0 fi echo "Backing up current installation..." mkdir -p "$BACKUP_DIR" cp -r "$VSCODE_DIR" "$BACKUP_DIR/VSCode-linux-x64-$(date +%Y%m%d-%H%M%S)" echo "Updating..." rm -rf "$VSCODE_DIR" mv "$TEMP_DIR/extracted/VSCode-linux-x64" "$VSCODE_DIR" rm -rf "$TEMP_DIR" CSS_FILE="$VSCODE_DIR/resources/app/out/vs/workbench/workbench.desktop.main.css" echo "Re-applying custom CSS patch \ (menubar=${MENUBAR_FONT_SIZE}, dropdown=${DROPDOWN_FONT_SIZE})..." cat >> "$CSS_FILE" << CSSEOF .menubar-menu-title{font-size:${MENUBAR_FONT_SIZE}!important}\ .menubar>.menubar-menu-button{font-size:${MENUBAR_FONT_SIZE}!important}\ .monaco-menu-option{font-size:${DROPDOWN_FONT_SIZE}!important;\ line-height:34px!important}\ .monaco-menu .action-label:not(.codicon)\ {font-size:${DROPDOWN_FONT_SIZE}!important}\ .menubar-menu-items-holder .monaco-menu .action-item .action-label\ {font-size:${DROPDOWN_FONT_SIZE}!important} CSSEOF PRODUCT_JSON="$VSCODE_DIR/resources/app/product.json" if [ -f "$PRODUCT_JSON" ]; then echo "Removing checksums to prevent integrity warning..." python3 -c " import json with open('$PRODUCT_JSON','r') as f: data=json.load(f) data.pop('checksums', None) with open('$PRODUCT_JSON','w') as f: json.dump(data,f,indent=2) print('Done.') " fi echo "=== Update complete: $CURRENT_VERSION -> $NEW_VERSION ==="</code></pre> </div> </div> <div class="paragraph"> <p>스크립트:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>최신 안정 버전을 다운로드하세요</p> </li> <li> <p>현재 버전과 다른지 확인해</p> </li> <li> <p>현재 설치(타임스탬프된)를`~/apps/vscode-backup/`</p> </li> <li> <p>설치 폴더를 교체하세요</p> </li> <li> <p><strong>재 적용</strong>메인 메뉴 CSS 패치</p> </li> <li> <p><strong>체크섬을 삭제하세요</strong> de `product.json`무결성 경고를 피하기 위해</p> </li> </ol> </div> <div class="paragraph"> <p>참고: 맞춤 CSS 확장 및 파일을 통한 Explorer 창 맞춤 설정`~/.vscode-custom-css/custom.css`설치 폴더 밖에 있기 때문에 업데이트를 살아남는다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_관련_파일_개요">관련 파일 — 개요</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle rectangle "설치 VS Code (~/apps/VSCode-linux-x64/)" #LightCoral { component "workbench.desktop\n.main.css" as css #LightCoral component "product.json" as product #LightCoral component "바이너리 bin/code" as binary #LightCoral } rectangle "사용자 설정\n(~/.config/Code/)" #LightGreen { component "settings.json" as settings #LightGreen component "확장/" as extensions #LightGreen } rectangle "지속적인 커스터마이징\n(~/.vscode-custom-css/)" #SkyBlue { component "custom.css (확대: 1.25)" as customcss #SkyBlue } rectangle "자동화 (~/apps/)" #LightYellow { component "vscode-update.sh" as script #LightYellow component "vscode-backup/" as backup #LightYellow } script ..> css : Re-patch après MAJ script ..> product : Supprime checksums\naprès MAJ settings --> customcss : Référence via\nvscode_custom_css.imports extensions ..> css : Custom CSS Loader\ninjecte custom.css note bottom of css **Ne survit pas** aux mises à jour Re-patché par le script end note note bottom of customcss **Survit** aux mises à jour Vit hors du dossier d'installation end note note bottom of settings **Survit** aux mises à jour Vit dans ~/.config/ end note @enduml</pre> </div> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 28.5714%;"> <col style="width: 42.8571%;"> <col style="width: 28.5715%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">길</th> <th class="tableblock halign-left valign-top">역할</th> <th class="tableblock halign-left valign-top">업데이트를 살아남나요?</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>~/apps/VSCode-linux-x64/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">IDE 설치</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">아니요 (대체됨)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>~/apps/VSCode-linux-x64/resources/app/out/vs/workbench/workbench.desktop.main.css</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">워크벤치 CSS (메뉴, 드롭다운)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">아니요 (스크립트에 의해 재패치됨)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>~/apps/VSCode-linux-x64/resources/app/product.json</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">무결성 체크섬</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">아니 (스크립트에 의해 재정리됨)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>~/apps/vscode-update.sh</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">자동 업데이트 스크립트</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">예</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>~/.config/Code/User/settings.json</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">사용자 설정 (fontSize, custom CSS)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">예</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>~/.vscode-custom-css/custom.css</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Explorer용 커스텀 CSS (줌)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">예</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_배운_교훈">배운 교훈</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif skinparam ArrowColor #444444 rectangle "**로컬 설치**\n 홈에" as install #LightGreen { card "sudo 없이 CSS/config을 수정하기 위해" as i1 card "opencode+LLM은 모든 것을 수정할 수 있다" as i2 card "롤백 = 복원 타임스탬프가 적용된 백업" as i3 } rectangle "CSS 커스터마이징 줌 vs 글꼴 크기" as css #LightYellow { card "줌 > 폰트 크기 컴포넌트 목록을 위한" as c1 card "JS 레이아웃 오버라이드 높이/줄간격" as c2 card "확장 Custom CSS 활성화가 필요합니다 수동 (Ctrl+Shift+P)" as c3 } rectangle "**자동화** 업데이트 스크립트" as auto #LightCoral { card "재패치 CSS 후 각 MAJ" as a1 card "체크섬 삭제\n product.json" as a2 card "타임스탬프가 있는 백업\n 교체 전" as a3 } install -right-> css : ensuite css -right-> auto : enfin note top of install Contrôle total sans élévation de privilèges end note note top of auto Sans script, chaque MAJ efface les patches CSS end note @enduml</pre> </div> </div> <div class="sect2"> <h3 id="_홈에_설치하면_모든_것이_해제됩니다">홈에 설치하면 모든 것이 해제됩니다</h3> <div class="paragraph"> <p>로컬 설치에서`~/apps`VS Code에 대한 완전한 제어를 제공합니다:</p> </div> <div class="ulist"> <ul> <li> <p>없`sudo`CSS 또는 구성을 수정하려면</p> </li> <li> <p>opencode+LLM 에이전트는 IDE의 구성 파일과 에셋에 쓸 수 있습니다.</p> </li> <li> <p>트리비얼 롤백: 타임스탬프가 있는 백업 복원</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_zoom_font_size_목록_컴포넌트에_대해">zoom` > <code>font-size</code> 목록 컴포넌트에 대해</h3> <div class="paragraph"> <p>VS Code는 JavaScript를 통해 줄 높이를 제어합니다. 수정`font-size`레이아웃 엔진이 할당한 높이를 만질 수 없으면 텍스트가 넘쳐 흐릅니다. 속성`zoom`부모 컨테이너를 비율대로 확대하면 이 문제를 피할 수 있다.</p> </div> </div> <div class="sect2"> <h3 id="_custom_css_확장은_명시적_활성화가_필요합니다">Custom CSS 확장은 명시적 활성화가 필요합니다.</h3> <div class="paragraph"> <p>이것은 'set and forget' 설정이 아닙니다. 맞춤 CSS 파일의 모든 수정은 명령어 팔레트에서 'Enable Custom CSS and JS’를 다시 실행해야 합니다 (<code>Ctrl+Shift+P</code>).</p> </div> </div> <div class="sect2"> <h3 id="_업데이트_스크립트는_필수적입니다">업데이트 스크립트는 필수적입니다.</h3> <div class="paragraph"> <p>스크립트 없이 VS Code 업데이트마다 워크벤치의 CSS 패치가 삭제됩니다. 스크립트`vscode-update.sh`다운로드, 교체, 재패치 및 체크섬 정리를 자동화합니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_빠른_참조">빠른 참조</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>VS Code 다운로드: <a href="https://code.visualstudio.com/Download" class="bare">https://code.visualstudio.com/Download</a></p> </li> <li> <p>확장 프로그램 Custom CSS 및 JS 로더 :`be5invis.vscode-custom-css`</p> </li> <li> <p>VS Code Explorer 폰트 네이티브 설정을 요청하는 이슈 :https://github.com/microsoft/vscode/issues/149[github.com/microsoft/vscode#149]</p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0102_migration_gradle_script_to_plugin_post.html Thu, 16 Apr 2026 00:00:00 +0000 blog/2026/0102_migration_gradle_script_to_plugin_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_배경_및_목적">배경 및 목적</a> <ul class="sectlevel2"> <li><a href="#_시작점">시작점</a></li> <li><a href="#_목표">목표</a></li> </ul> </li> <li><a href="#_첫_번째_장애물_ruby_gems">첫 번째 장애물 : `ruby { gems() }</a> <ul class="sectlevel2"> <li><a href="#_그루비_구문_설탕이_숨기는_것">그루비 구문 설탕이 숨기는 것</a></li> <li><a href="#_메커니즘의_분해">메커니즘의 분해</a></li> </ul> </li> <li><a href="#_세_부분으로_구성된_해결책">세 부분으로 구성된 해결책</a> <ul class="sectlevel2"> <li><a href="#_1부_rubygems를_위한_ivy_리포지터리">1부: rubygems를 위한 Ivy 리포지터리</a></li> <li><a href="#_제2부_asciidoctorgems_종속성">제2부: asciidoctorGems 종속성</a></li> <li><a href="#_3부_settings_gradle_kts">3부 : settings.gradle.kts</a></li> </ul> </li> <li><a href="#_api의_바이트코드를_통한_내부_검사">API의 바이트코드를 통한 내부 검사</a> <ul class="sectlevel2"> <li><a href="#_왜_javap">왜 <code>javap</code> ?</a></li> <li><a href="#_작업의_계층">작업의 계층</a></li> <li><a href="#_발견_의_forkoptions">발견 의 `forkOptions</a></li> <li><a href="#_javaforkoptions의_api_grolifant">JavaForkOptions의 API (grolifant)</a></li> <li><a href="#_revealjsextension">RevealJSExtension</a></li> </ul> </li> <li><a href="#_자바_툴체인_구성">자바 툴체인 구성</a> <ul class="sectlevel2"> <li><a href="#_javatoolchainservice의_문제">JavaToolchainService의 문제</a></li> </ul> </li> <li><a href="#_자동_docker_감지">자동 Docker 감지</a> <ul class="sectlevel2"> <li><a href="#_컨텍스트">컨텍스트</a></li> <li><a href="#_전략">전략</a></li> </ul> </li> <li><a href="#_최종_결과">최종 결과</a> <ul class="sectlevel2"> <li><a href="#_소비자용_buildscript">소비자용 buildscript</a></li> <li><a href="#_settings_gradle_kts">settings.gradle.kts</a></li> </ul> </li> <li><a href="#_함정과_해결책_요약">함정과 해결책 요약</a></li> <li><a href="#_조사_방법_javap을_사용해_알_수_없는_api_읽기">조사 방법: javap을 사용해 알 수 없는 API 읽기</a> <ul class="sectlevel2"> <li><a href="#_원칙">원칙</a></li> <li><a href="#_1단계_gradle_캐시에서_jar_파일_찾기">1단계: Gradle 캐시에서 JAR 파일 찾기</a></li> <li><a href="#_2단계_jar의_클래스_나열">2단계: jar의 클래스 나열</a></li> <li><a href="#_단계_3_클래스_검사">단계 3: 클래스 검사</a></li> <li><a href="#_단계_4_계층_구조_위로_이동">단계 4: 계층 구조 위로 이동</a></li> <li><a href="#_단계_5_알_수_없는_유형_추적">단계 5 : 알 수 없는 유형 추적</a></li> <li><a href="#_단계_6_프로젝트_확장자_확인">단계 6 : 프로젝트 확장자 확인</a></li> <li><a href="#_방법_요약">방법 요약</a></li> </ul> </li> <li><a href="#_다음_단계">다음 단계</a></li> </ul> </div> <div class="sect1"> <h2 id="_배경_및_목적">배경 및 목적</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_시작점">시작점</h3> <div class="paragraph"> <p>프로젝트`slider-gradle`AsciiDoc 파일로부터 Gradle 플러그인을 통해 Reveal.js 발표를 생성합니다`org.asciidoctor.jvm.revealjs`. 주요 작업 설정`asciidoctorRevealJs`루트 빌드스크립트에 직접 있었다`build.gradle.kts`[No output]</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">plugins { id("org.asciidoctor.jvm.revealjs") } apply<slides.SlidesPlugin>() project.tasks.getByName<AsciidoctorJRevealJSTask>(TASK_ASCIIDOCTOR_REVEALJS) { repositories { ruby { gems() } } revealjs { version = "3.1.0" templateGitHub { setOrganisation("hakimel") setRepository("reveal.js") setTag("3.9.1") } } revealjsOptions { // ... configuration complète } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_목표">목표</h3> <div class="paragraph"> <p>이 전체 구성을`buildSrc/src/main/kotlin/slides/SlidesPlugin.kt`소비자 buildscript가 다음과 같이 축소되도록 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">apply<slides.SlidesPlugin>()</code></pre> </div> </div> <div class="paragraph"> <p>플러그인은 완전히 자율적이어야 함: 자체적으로 플러그인 종속성을 적용하고, 레포지토리를 구성하며, 루비 젬을 관리해야 합니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_첫_번째_장애물_ruby_gems">첫 번째 장애물 : `ruby { gems() }</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_그루비_구문_설탕이_숨기는_것">그루비 구문 설탕이 숨기는 것</h3> <div class="paragraph"> <p>라인`repositories { ruby { gems() } }`이는 빌드스크립트 실행 컨텍스트에서만 사용할 수 있는 Groovy DSL 확장입니다. 이는 buildSrc에서 접근 가능한 정적 Kotlin API가 아닙니다.</p> </div> <div class="paragraph"> <p>그에게 전화를 걸려고 시도하면서`SlidesPlugin.kt`, 컴파일이 즉시 실패합니다.</p> </div> </div> <div class="sect2"> <h3 id="_메커니즘의_분해">메커니즘의 분해</h3> <div class="paragraph"> <p>그레이들 캐시 분석 후 (<code>~/.gradle/caches/modules-2/files-2.1/rubygems/</code>), 파일에서 발견합니다`ivy-3.1.0.xml`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><artifact type='gem' url='https://rubygems.org/gems/asciidoctor-revealjs-3.1.0.gem' /></code></pre> </div> </div> <div class="paragraph"> <p>`ruby { gems() }`실제로 수행하고 있었다<strong>세 개의 별도 작업</strong>:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Ivy 레포를 가리키는 저장`https://rubygems.org/gems/`</p> </li> <li> <p>그룹 제외`rubygems`충돌을 피하기 위한 Maven 저장소</p> </li> <li> <p>구성에 gem을 저장`asciidoctorGems`JRuby가 런타임에 이를 로드하도록</p> </li> </ol> </div> <div class="paragraph"> <p>이 세 가지 책임은 Kotlin에서 별도로 재현해야 합니다</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_세_부분으로_구성된_해결책">세 부분으로 구성된 해결책</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_1부_rubygems를_위한_ivy_리포지터리">1부: rubygems를 위한 Ivy 리포지터리</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">project.repositories.mavenCentral() { content { excludeGroup("rubygems") } } project.repositories.ivy { url = project.uri("https://rubygems.org/gems/") patternLayout { artifact("[module]-[revision].gem") } <i class="conum" data-value="1"></i><b>(1)</b> metadataSources { artifact() } content { includeGroup("rubygems") } }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>확장`.gem`하드코딩되어야 합니다.<code>[ext]`기본적으로 해결하는</code>.jar`, 이는 오류를 일으킵니다`Resource missing`.</td> </tr> </table> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> Ivy 레포는 바로 위에 선언됩니다.`project.repositories`그리고 블록 안에 있지 않음`repositories { }`왜냐하면 이 블록의 수신기가 아니기 때문에`RepositoryHandler`Gradle 표준이지만 확장과 호환되지 않는 grolifant API`ivy`Kotlin DSL. </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_제2부_asciidoctorgems_종속성">제2부: asciidoctorGems 종속성</h3> <div class="paragraph"> <p>플러그인`org.asciidoctor.jvm.gems`먼저 적용해야 합니다 — 구성을 만듭니다.<code>asciidoctorGems`그리고 작업`asciidoctorGemsPrepare</code>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">project.plugins.apply("org.asciidoctor.jvm.gems") project.plugins.apply("org.asciidoctor.jvm.revealjs") <i class="conum" data-value="1"></i><b>(1)</b> project.dependencies { add("asciidoctorGems", "rubygems:asciidoctor-revealjs:3.1.0@gem") <i class="conum" data-value="2"></i><b>(2)</b> }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>적용 순서는 중요합니다 :`gems`이전`revealjs`. <2> 수식어`@gem`의존성에 올바른 확장을 강제합니다.</td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_3부_settings_gradle_kts">3부 : settings.gradle.kts</h3> <div class="paragraph"> <p>`dependencyResolutionManagement`안에`settings.gradle.kts`프로젝트가 자체 저장소를 선언하도록 허용해야 합니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Suppress("UnstableApiUsage") dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.PREFER_PROJECT) }</code></pre> </div> </div> <div class="paragraph"> <p>이 라인이 없으면 Gradle은 플러그인에 선언된 저장소를 무시하고, gem 의존성 해결이 실패합니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_api의_바이트코드를_통한_내부_검사">API의 바이트코드를 통한 내부 검사</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_왜_javap">왜 <code>javap</code> ?</h3> <div class="paragraph"> <p>플러그인`asciidoctor-gradle-jvm-slides`버전에 있습니다`4.0.0-alpha.1`. 문서는 존재하지 않거나 불완전합니다. 신뢰할 수 있는 유일한 소스는 컴파일된 클래스를 직접 검사하는 것이다.</p> </div> </div> <div class="sect2"> <h3 id="_작업의_계층">작업의 계층</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">javap -p -classpath asciidoctor-gradle-jvm-slides-4.0.0-alpha.1.jar \ org.asciidoctor.gradle.jvm.slides.AsciidoctorJRevealJSTask</code></pre> </div> </div> <div class="paragraph"> <p>결과 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">public class AsciidoctorJRevealJSTask extends org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask implements org.asciidoctor.gradle.base.slides.SlidesToExportAware</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_발견_의_forkoptions">발견 의 `forkOptions</h3> <div class="paragraph"> <p>검사하면서`AbstractAsciidoctorTask`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">javap -p -classpath asciidoctor-gradle-jvm-4.0.0-alpha.1.jar \ org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask | grep -i "fork\|exec\|jvm"</code></pre> </div> </div> <div class="paragraph"> <p>다음과 같습니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">final org.ysb33r.grolifant.api.v4.JavaForkOptions javaForkOptions; public void forkOptions(org.gradle.api.Action<org.ysb33r.grolifant.api.v4.JavaForkOptions>); public static final org.asciidoctor.gradle.base.process.ProcessMode JAVA_EXEC;</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_javaforkoptions의_api_grolifant">JavaForkOptions의 API (grolifant)</h3> <div class="paragraph"> <p>`javaLauncher`이 작업에는 존재하지 않습니다. 실제 API의`org.ysb33r.grolifant.api.v4.JavaForkOptions`노출 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">public void executable(java.lang.Object); <i class="conum" data-value="1"></i><b>(1)</b> public void setExecutable(java.lang.Object);</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>방법`executable(Object)`할당을 대체한다`executable = …​`컴파일되지 않는다 (`val`재할당할 수 없습니다).</td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_revealjsextension">RevealJSExtension</h3> <div class="paragraph"> <p>`revealjs { }`작업의 방법이 아닌<strong>프로젝트 연장</strong>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">javap -p -classpath asciidoctor-gradle-jvm-slides-4.0.0-alpha.1.jar \ org.asciidoctor.gradle.jvm.slides.RevealJSExtension</code></pre> </div> </div> <div class="paragraph"> <p>접근 방법 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">project.extensions.getByType<RevealJSExtension>().apply { version = "3.1.0" templateGitHub { setOrganisation("hakimel") setRepository("reveal.js") setTag("3.9.1") } }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_자바_툴체인_구성">자바 툴체인 구성</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_javatoolchainservice의_문제">JavaToolchainService의 문제</h3> <div class="paragraph"> <p>`JavaToolchainService`프로젝트 확장이 아닙니다. 다음 호출이 실패합니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// ERREUR : Extension of type 'JavaToolchainService' does not exist project.extensions.getByType<JavaToolchainService>()</code></pre> </div> </div> <div class="paragraph"> <p>올바른 API는`serviceOf`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">import org.gradle.kotlin.dsl.support.serviceOf project.tasks.getByName<AsciidoctorJRevealJSTask>(TASK_ASCIIDOCTOR_REVEALJS) { setInProcess("JAVA_EXEC") forkOptions { executable( project.serviceOf<JavaToolchainService>() .launcherFor { languageVersion.set(JavaLanguageVersion.of(17)) vendor.set(JvmVendorSpec.ADOPTIUM) } .get() .executablePath .asFile .absolutePath ) } }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_자동_docker_감지">자동 Docker 감지</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_컨텍스트">컨텍스트</h3> <div class="paragraph"> <p>Asciidoctor/JRuby 플러그인은 Java 17이 필요합니다. buildSrc의 Kotlin 2.0.x는 Java 25를 지원하지 않습니다(버전 파서가에서 크래시됩니다`"25.0.2"`). Gradle 데몬은 따라서 Java 17에서 실행되거나 Docker를 사용해야 합니다.</p> </div> </div> <div class="sect2"> <h3 id="_전략">전략</h3> <div class="olist arabic"> <ol class="arabic"> <li> <p>Docker 사용 가능 → 컨테이너를 통한 실행`eclipse-temurin:17`(기본 동작)</p> </li> <li> <p>Docker이 없음 + Java 17 → 로컬 실행</p> </li> <li> <p>Docker 없음 + Java > 17 → 명시적 오류</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val isDockerAvailable = try { Runtime.getRuntime().exec(arrayOf("docker", "info")).waitFor() == 0 } catch (e: Exception) { false } val javaVersion = JavaVersion.current().majorVersion.toInt() when { isDockerAvailable -> project.tasks.register<Exec>(TASK_ASCIIDOCTOR_REVEALJS) { group = GROUP_TASK_SLIDER description = "Slider settings and generation (via Docker)" dependsOn(TASK_CLEAN_SLIDES_BUILD) finalizedBy(TASK_DASHBOARD_SLIDES_BUILD) commandLine( "docker", "run", "--rm", "-v", "${project.rootDir.absolutePath}:/workspace", "-v", "${System.getProperty("user.home")}/.gradle:/root/.gradle", "-w", "/workspace", "eclipse-temurin:17", "./gradlew", TASK_ASCIIDOCTOR_REVEALJS ) workingDir = project.rootDir } javaVersion == 17 -> { project.repositories.mavenCentral() { content { excludeGroup("rubygems") } } project.repositories.ivy { url = project.uri("https://rubygems.org/gems/") patternLayout { artifact("[module]-[revision].gem") } metadataSources { artifact() } content { includeGroup("rubygems") } } project.extensions.getByType<RevealJSExtension>().apply { version = "3.1.0" templateGitHub { setOrganisation("hakimel") setRepository("reveal.js") setTag("3.9.1") } } project.tasks.getByName<AsciidoctorJRevealJSTask>(TASK_ASCIIDOCTOR_REVEALJS) { setInProcess("JAVA_EXEC") forkOptions { executable( project.serviceOf<JavaToolchainService>() .launcherFor { languageVersion.set(JavaLanguageVersion.of(17)) vendor.set(JvmVendorSpec.ADOPTIUM) } .get() .executablePath .asFile .absolutePath ) } // ... reste de la configuration } } else -> error( "Docker est requis pour exécuter $TASK_ASCIIDOCTOR_REVEALJS " + "avec Java $javaVersion. Installez Docker ou utilisez Java 17." ) }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_최종_결과">최종 결과</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_소비자용_buildscript">소비자용 buildscript</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">apply<slides.SlidesPlugin>()</code></pre> </div> </div> <div class="paragraph"> <p>그게 전부예요. 플러그인이 모든 책임을 집니다.</p> </div> </div> <div class="sect2"> <h3 id="_settings_gradle_kts">settings.gradle.kts</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">pluginManagement { repositories { mavenLocal() gradlePluginPortal() } } plugins { id("org.gradle.toolchains.foojay-resolver-convention") version "0.8.0" } @Suppress("UnstableApiUsage") dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.PREFER_PROJECT) } rootProject.name = "slider-gradle"</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_함정과_해결책_요약">함정과 해결책 요약</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 37.5%;"> <col style="width: 37.5%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">문제</th> <th class="tableblock halign-left valign-top">원인</th> <th class="tableblock halign-left valign-top">해결책</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">`ruby { gems() }`Kotlin에서 사용할 수 없음</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Groovy DSL 확장만</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">세 가지 별도의 메커니즘 : Ivy 저장소 + Maven 제외 +<code>asciidoctorGems</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Gradle가 찾는`.jar`대신에`.gem`</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`[ext]`해결하는`jar`기본적으로</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">하드코더`.gem`Ivy 패턴 + 한정자 안에`@gem`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>ivy { }`컴파일이 되지 않음`repositories { }</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">수신자 grolifant는 Kotlin DSL과 호환되지 않습니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">직접 통화`project.repositories.ivy { }`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">`javaLauncher`해결되지 않은</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">존재하지 않는 속성`AsciidoctorJRevealJSTask`</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>setInProcess("JAVA_EXEC")</code>+<code>forkOptions { executable(…​) }</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">`executable = …​`컴파일되지 않습니다</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">속성`val`안에`JavaForkOptions`그롤리팡</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">방법`executable(Object)`대신에</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>JavaToolchainService`를 통해 찾을 수 없음`extensions</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">이것은 Gradle 서비스이지, 확장이 아닙니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>project.serviceOf<JavaToolchainService>()</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">`revealjs { }`작업에서 해결되지 않음</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">프로젝트 확장, 작업 방법이 아님</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>project.extensions.getByType<RevealJSExtension>()</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Java 25에서 빌드가 충돌합니다</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Kotlin 2.0.x는 두 자리 숫자 버전의 Java를 파싱하지 않습니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">자동 Docker 감지 + Java 17 폴백</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_조사_방법_javap을_사용해_알_수_없는_api_읽기">조사 방법: javap을 사용해 알 수 없는 API 읽기</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_원칙">원칙</h3> <div class="paragraph"> <p>문서가 없거나 불완전할 때, 바이트코드가 진실의 원천입니다. <code>javap`는 JDK의 표준 도구로 파일을 디컴파일하는 도구입니다.</code>.class`읽을 수 있는 Java 서명, 소스 코드가 필요 없이.</p> </div> </div> <div class="sect2"> <h3 id="_1단계_gradle_캐시에서_jar_파일_찾기">1단계: Gradle 캐시에서 JAR 파일 찾기</h3> <div class="paragraph"> <p>Gradle은 모든 의존성을 다운로드합니다`~/.gradle/caches/modules-2/files-2.1/`. 첫 번째 단계는 검사할 클래스를 포함하는 jar을 찾는 것입니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">find ~/.gradle/caches -name "asciidoctor-gradle-jvm-slides*.jar" 2>/dev/null</code></pre> </div> </div> <div class="listingblock"> <div class="title">결과 :</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">/home/user/.gradle/caches/modules-2/files-2.1/org.asciidoctor/ asciidoctor-gradle-jvm-slides/4.0.0-alpha.1/.../ asciidoctor-gradle-jvm-slides-4.0.0-alpha.1.jar</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_2단계_jar의_클래스_나열">2단계: jar의 클래스 나열</h3> <div class="paragraph"> <p>클래스를 검사하기 전에, JAR에 실제로 존재하는지 확인합니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">jar tf asciidoctor-gradle-jvm-slides-4.0.0-alpha.1.jar | grep -i "RevealJS\|revealjs"</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_단계_3_클래스_검사">단계 3: 클래스 검사</h3> <div class="listingblock"> <div class="title">이것은 사용 가능한 모든 클래스를 보여줍니다 : <code>AsciidoctorJRevealJSTask</code>, <code>RevealJSExtension</code>, <code>RevealJSOptions</code>, 등</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">javap -p -classpath asciidoctor-gradle-jvm-slides-4.0.0-alpha.1.jar \ org.asciidoctor.gradle.jvm.slides.AsciidoctorJRevealJSTask</code></pre> </div> </div> <div class="paragraph"> <p>옵션`-p`비공개 멤버를 포함하여 모든 멤버를 표시합니다. 결과는 즉시 핵심 라인을 보여줍니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">public class AsciidoctorJRevealJSTask extends org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_단계_4_계층_구조_위로_이동">단계 4: 계층 구조 위로 이동</h3> <div class="paragraph"> <p>작업이 확장된다.<code>AbstractAsciidoctorTask</code>. 그 차례에 검사한다 먼저 그의 jar를 찾은 뒤:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">find ~/.gradle/caches -name "asciidoctor-gradle-jvm-[0-9]*.jar" 2>/dev/null javap -p -classpath asciidoctor-gradle-jvm-4.0.0-alpha.1.jar \ org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask | grep -i "fork\|exec\|jvm\|java"</code></pre> </div> </div> <div class="paragraph"> <p>거기서 우리가 발견한다`forkOptions`, <code>JAVA_EXEC</code>, et <code>javaForkOptions</code> 유형`org.ysb33r.grolifant.api.v4.JavaForkOptions`.</p> </div> </div> <div class="sect2"> <h3 id="_단계_5_알_수_없는_유형_추적">단계 5 : 알 수 없는 유형 추적</h3> <div class="paragraph"> <p>`JavaForkOptions`는 알려지지 않은 grolifant 클래스입니다. 우리는 그 jar를 찾습니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">find ~/.gradle/caches -name "grolifant*.jar" 2>/dev/null</code></pre> </div> </div> <div class="paragraph"> <p>그 후에 그것을 검사합니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">javap -p -classpath grolifant40-legacy-api-2.0.0-alpha.6.jar \ org.ysb33r.grolifant.api.v4.JavaForkOptions</code></pre> </div> </div> <div class="paragraph"> <p>거기에서 찾을 수 있습니다`executable(java.lang.Object)<code>— 호출되어야 할 올바른 메서드, 대조적으로`executable = …​`속성이라서 컴파일이 되지 않습니다`val</code>.</p> </div> </div> <div class="sect2"> <h3 id="_단계_6_프로젝트_확장자_확인">단계 6 : 프로젝트 확장자 확인</h3> <div class="paragraph"> <p>를 위해`revealjs { }`, 질문은 이것이 작업의 방법이었는가? 또는 프로젝트 확장 ? 검사`AsciidoctorJRevealJSTask` 어떤 방법도 보여주지 않는다.<code>revealjs</code>. 그때 점검합니다`RevealJSExtension`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">javap -p -classpath asciidoctor-gradle-jvm-slides-4.0.0-alpha.1.jar \ org.asciidoctor.gradle.jvm.slides.RevealJSExtension | head -5</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">public class RevealJSExtension implements groovy.lang.GroovyObject { public static final java.lang.String NAME;</code></pre> </div> </div> <div class="paragraph"> <p>존재하는`NAME`확인합니다. 이는 프로젝트에 등록된 확장 기능입니다, 접근 가능한`project.extensions.getByType<RevealJSExtension>()`.</p> </div> </div> <div class="sect2"> <h3 id="_방법_요약">방법 요약</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 75%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">단계</th> <th class="tableblock halign-left valign-top">행동</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>find ~/.gradle/caches -name "*.jar"</code>— jar 찾기</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>jar tf jar.jar | grep NomClasse</code>— 클래스가 존재하는지 확인</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>javap -p -classpath jar.jar NomCompletClasse</code>— 클래스를 점검하다</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">식별자`extends`그리고 계층을 올라가다</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">자신들의 jars에서 알려지지 않은 유형을 추적하다</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">6</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">검색하다`NAME`프로젝트 확장을 식별하기 위해</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>이 방법은 문서화되지 않은 API를 가진 모든 Gradle 플러그인에 적용됩니다. 또는 알파 버전이 기존 문서와 더 이상 일치하지 않는.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_다음_단계">다음 단계</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 buildSrc 플러그인은 Gradle Plugin Portal 또는 Maven Local에 게시된 독립된 프로젝트로 추출됩니다. 소비자 buildscript는 다음과 같이 될 것입니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">plugins { id("slides") version "1.0.0" }</code></pre> </div> </div> <div class="paragraph"> <p>Et <code>settings.gradle.kts`최소한으로 축소될 것이며 참조를 갖지 않을`foojay-resolver-convention</code>, 플러그인 자체에서 관리되거나 사전 요구 사항으로 문서화된 JDK 프로비저닝.</p> </div> </div> </div> https://cheroliv.com/blog/2026/0101_jbake_portfolio_post.html Thu, 15 Jan 2026 00:00:00 +0000 blog/2026/0101_jbake_portfolio_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_건축_비전">건축 비전</a> <ul class="sectlevel2"> <li><a href="#_주도_원칙">주도 원칙</a></li> <li><a href="#_전략적_선택_포트폴리오를_위한_asciidoc">전략적 선택 : 포트폴리오를 위한 AsciiDoc</a></li> <li><a href="#_데이터_모델">데이터 모델</a></li> </ul> </li> <li><a href="#_상세한_사용_사례">상세한 사용 사례</a> <ul class="sectlevel2"> <li><a href="#_uc1_포트폴리오에_항목_추가">UC1 : 포트폴리오에 항목 추가</a> <ul class="sectlevel3"> <li><a href="#_정상_흐름">정상 흐름</a></li> <li><a href="#_생성할_파일의_템플릿">생성할 파일의 템플릿</a></li> <li><a href="#_검증_포인트">검증 포인트</a></li> </ul> </li> <li><a href="#_uc2_포트폴리오에서_항목_삭제">UC2 : 포트폴리오에서 항목 삭제</a> <ul class="sectlevel3"> <li><a href="#_명목_플럭스">명목 플럭스</a></li> <li><a href="#_대체_전략_아카이빙">대체 전략: 아카이빙</a></li> <li><a href="#_리소스_정리">리소스 정리</a></li> </ul> </li> <li><a href="#_uc3_비공개초안로_설정">UC3 : 비공개(초안)로 설정</a> <ul class="sectlevel3"> <li><a href="#_명목_흐름">명목 흐름</a></li> <li><a href="#_가능한_상태">가능한 상태</a></li> <li><a href="#_일반적인_사용_사례">일반적인 사용 사례</a></li> </ul> </li> </ul> </li> <li><a href="#_템플릿_아키텍처">템플릿 아키텍처</a> <ul class="sectlevel2"> <li><a href="#_재사용_가능한_템플릿_전략">재사용 가능한 템플릿 전략</a></li> <li><a href="#_데이터_추출_패턴">데이터 추출 패턴</a></li> <li><a href="#_명명_규칙">명명 규칙</a></li> </ul> </li> <li><a href="#_출판_워크플로우">출판 워크플로우</a> <ul class="sectlevel2"> <li><a href="#_개발_파이프라인">개발 파이프라인</a></li> <li><a href="#_환경">환경</a></li> </ul> </li> <li><a href="#_확장성">확장성</a> <ul class="sectlevel2"> <li><a href="#_새로운_속성_추가">새로운 속성 추가</a></li> <li><a href="#_고급_분류">고급 분류</a></li> </ul> </li> <li><a href="#_모범_사례">모범 사례</a> <ul class="sectlevel2"> <li><a href="#_파일_구성">파일 구성</a></li> <li><a href="#_콘텐츠_관리">콘텐츠 관리</a></li> <li><a href="#_성능">성능</a></li> </ul> </li> <li><a href="#_결론">결론</a></li> </ul> </div> <div class="sect1"> <h2 id="_건축_비전">건축 비전</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_주도_원칙">주도 원칙</h3> <div class="paragraph"> <p>아키텍처는 <strong>관심사의 분리</strong> 원리에 기반을 두고 있습니다 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Contenu</strong> : 풍부한 메타데이터가 포함된 구조화된 AsciiDoc 파일</p> </li> <li> <p><strong>소개</strong> : 재사용 가능한 Thymeleaf 템플릿</p> </li> <li> <p><strong>데이터</strong> : JBake에 의해 AsciiDoc 속성에서 자동으로 추출된 모델</p> </li> <li> <p><strong>스타일</strong> : Bootstrap 5를 시각적 일관성을 위해</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_전략적_선택_포트폴리오를_위한_asciidoc">전략적 선택 : 포트폴리오를 위한 AsciiDoc</h3> <table class="tableblock frame-all grid-all stretch"> <caption class="title">Table 1. 왜 아스키독?</caption> <colgroup> <col style="width: 33.3333%;"> <col style="width: 66.6667%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">기준</th> <th class="tableblock halign-left valign-top">장점</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">일관성</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">블로그 글과 같은 형식</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">메타데이터</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">구조화된 및 확장 가능한 속성 (<code>project-*</code>)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">유지보수성</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">간단한 텍스트 편집, Git 버전 관리 가능</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">유연성</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">풍부한 콘텐츠(표, 코드, 이미지)를 포함할 수 있습니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">템플릿화</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">JBake은 Thymeleaf용 속성을 자동으로 추출합니다.</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_데이터_모델">데이터 모델</h3> <div class="paragraph"> <p>각 포트폴리오 프로젝트는 다음과 같은 AsciiDoc 문서입니다:</p> </div> <div class="ulist"> <ul> <li> <p><strong>헤더 메타데이터</strong> : 구조화된 정보(클라이언트, 기간, 기술 등)</p> </li> <li> <p><strong>문서 본문</strong> : 서술적 설명, 도전 과제, 해결책, 결과</p> </li> <li> <p><strong>s용자 정의 속성</strong> : 접두사가 된`project-*`자동 추출을 위해</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam handwritten false class ProjetAsciiDoc { +titre: String +jbake-type: "프로젝트" +jbake-status: published|draft +jbake-date: Date +jbake-tags: List<String> -- +project-category: String +project-client: String +project-duration: String +project-role: String +project-thumbnail: String +project-gallery: List<String> +project-tech-stack: String +project-highlights: List<String> +project-demo-url: String +project-github-url: String -- +body: HTML (converti) } class JBakeEngine { +parse(asciidoc) +extractMetadata() +convertToHTML() } class ThymeleafTemplate { +portfolio.html +project.html +partials/project-card.html } class PortfolioPage { +published_projects: List +filtres: categories } ProjetAsciiDoc --> JBakeEngine : parse JBakeEngine --> ThymeleafTemplate : fournit données ThymeleafTemplate --> PortfolioPage : génère @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_상세한_사용_사례">상세한 사용 사례</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_uc1_포트폴리오에_항목_추가">UC1 : 포트폴리오에 항목 추가</h3> <div class="sect3"> <h4 id="_정상_흐름">정상 흐름</h4> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "편집기\n텍스트" as editor participant "파일 AsciiDoc" as file participant "JBake 엔진" as jbake participant "사이트 정적" as site dev -> editor : Créer nouveau fichier activate editor editor -> file : portfolio/nouveau-projet.adoc activate file dev -> editor : Rédiger en-tête avec métadonnées\n(titre, type=project, status=published,\nattributs project-*) dev -> editor : Rédiger contenu narratif\n(contexte, défis, solutions) dev -> editor : Ajouter images dans assets/img/portfolio/ editor -> file : Sauvegarder deactivate editor dev -> jbake : Lancer build (jbake -b) activate jbake jbake -> file : Lire et parser jbake -> jbake : Extraire métadonnées jbake -> jbake : Convertir AsciiDoc → HTML jbake -> jbake : Appliquer template project.html jbake -> jbake : Ajouter à la liste portfolio.html jbake -> site : Générer pages statiques deactivate jbake dev -> site : Vérifier résultat activate site site --> dev : Afficher projet deactivate site @enduml</pre> </div> </div> </div> <div class="sect3"> <h4 id="_생성할_파일의_템플릿">생성할 파일의 템플릿</h4> <div class="paragraph"> <p>개발자는 만든다`content/portfolio/nom-projet.adoc`표준화된 구조와 함께 :</p> </div> <div class="ulist"> <ul> <li> <p>필수 속성을 모두 갖춘 헤더</p> </li> <li> <p>표준화된 섹션 (컨텍스트, 도전, 솔루션, 결과)</p> </li> <li> <p>일관된 이미지 명명법</p> </li> </ul> </div> </div> <div class="sect3"> <h4 id="_검증_포인트">검증 포인트</h4> <div class="ulist"> <ul> <li> <p>필수 속성이 존재합니다 (<code>jbake-type</code>, <code>jbake-status</code>, <code>project-thumbnail</code>)</p> </li> <li> <p>참조된 이미지는 에 존재합니다.<code>assets/img/portfolio/</code></p> </li> <li> <p>JBake 빌드가 오류 없이 성공합니다</p> </li> <li> <p>포트폴리오 페이지에 프로젝트가 나타납니다</p> </li> <li> <p>개별 프로젝트 페이지가 올바르게 표시됩니다</p> </li> </ul> </div> </div> </div> <div class="sect2"> <h3 id="_uc2_포트폴리오에서_항목_삭제">UC2 : 포트폴리오에서 항목 삭제</h3> <div class="sect3"> <h4 id="_명목_플럭스">명목 플럭스</h4> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "시스템 파일" as fs participant "JBake 엔진" as jbake participant "사이트 정적" as site database "캐시 JBake" as cache dev -> fs : Supprimer portfolio/projet-ancien.adoc activate fs fs --> dev : Fichier supprimé deactivate fs dev -> fs : (Optionnel) Supprimer images associées\nassets/img/portfolio/projet-ancien-* activate fs fs --> dev : Images supprimées deactivate fs dev -> cache : Nettoyer cache JBake activate cache cache --> dev : Cache vidé deactivate cache dev -> jbake : Rebuild complet (jbake -b) activate jbake jbake -> jbake : Scanner content/portfolio/ jbake -> jbake : Projet absent → non généré jbake -> jbake : Régénérer portfolio.html\n(sans le projet supprimé) jbake -> site : Déployer nouveau build deactivate jbake dev -> site : Vérifier activate site site --> dev : Projet absent de la liste deactivate site @enduml</pre> </div> </div> </div> <div class="sect3"> <h4 id="_대체_전략_아카이빙">대체 전략: 아카이빙</h4> <div class="paragraph"> <p>영구적으로 삭제하는 대신, 폴더를 만들 수 있는 가능성`content/portfolio/archive/`:</p> </div> <div class="ulist"> <ul> <li> <p>파일을 삭제하는 대신 이동하세요</p> </li> <li> <p>쉽게 복원할 수 있습니다</p> </li> <li> <p>Git 기록을 더 명확하게 유지합니다</p> </li> </ul> </div> </div> <div class="sect3"> <h4 id="_리소스_정리">리소스 정리</h4> <div class="ulist"> <ul> <li> <p>고아 이미지 확인`assets/img/portfolio/`</p> </li> <li> <p>다른 프로젝트에 참조되지 않은 이미지 삭제</p> </li> <li> <p>JBake 캐시를 정리하여 유령 참조를 방지하기</p> </li> </ul> </div> </div> </div> <div class="sect2"> <h3 id="_uc3_비공개초안로_설정">UC3 : 비공개(초안)로 설정</h3> <div class="sect3"> <h4 id="_명목_흐름">명목 흐름</h4> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "파일\nAsciiDoc" as file participant "JBake\n엔진" as jbake participant "정적 사이트" as site dev -> file : Ouvrir portfolio/projet.adoc activate file dev -> file : Modifier attribut\n:jbake-status: published\n↓\n:jbake-status: draft file --> dev : Sauvegardé deactivate file dev -> jbake : Rebuild (jbake -b) activate jbake jbake -> file : Parser le fichier jbake -> jbake : Détecter status=draft jbake -> jbake : Exclure de published_projects jbake -> jbake : Ne pas créer page publique note right Le projet existe toujours mais n'est pas publié end note jbake -> site : Générer site (sans ce projet) deactivate jbake dev -> site : Vérifier portfolio activate site site --> dev : Projet absent de la liste publique deactivate site @enduml</pre> </div> </div> </div> <div class="sect3"> <h4 id="_가능한_상태">가능한 상태</h4> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE [*] --> Draft : Création initiale Draft --> Published : Validation et publication Published --> Draft : Retrait temporaire Draft --> Archived : Projet abandonné Published --> Archived : Projet obsolète Archived --> [*] : Suppression définitive Published --> Published : Mises à jour note right of Draft :jbake-status: draft Non visible publiquement Utile pour projets en cours end note note right of Published :jbake-status: published Visible sur le portfolio Indexé par JBake end note note right of Archived Déplacé dans archive/ ou jbake-status: archived Non publié mais conservé end note @enduml</pre> </div> </div> </div> <div class="sect3"> <h4 id="_일반적인_사용_사례">일반적인 사용 사례</h4> <div class="ulist"> <ul> <li> <p><strong>작성 중인 프로젝트</strong> : 드래프트로 만들고, 준비가 되면 게시</p> </li> <li> <p><strong>임시 기밀 프로젝트</strong> : 클라이언트 승인 동안 초안으로 전환</p> </li> <li> <p><strong>주요 업데이트</strong> : 초안으로 전환, 수정, 다시 게시</p> </li> <li> <p><strong>A/B testing</strong> : 초안으로 복제해서 테스트하고, 가장 좋은 버전 공개</p> </li> </ul> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_템플릿_아키텍처">템플릿 아키텍처</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_재사용_가능한_템플릿_전략">재사용 가능한 템플릿 전략</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "Thymeleaf 템플릿" { component [index.html] as index component [portfolio.html] as portfolio component [project.html] as project package "부분들" { component [header.html] as header component [footer.html] as footer component [project-card.html] as card component [tech-badge.html] as badge component [gallery.html] as gallery } } package "데이터 JBake" { database "게시된 프로젝트" as data database "내용 (프로젝트)" as content } index --> header index --> footer portfolio --> header portfolio --> footer portfolio --> card data --> portfolio : itération project --> header project --> footer project --> badge project --> gallery content --> project : projet individuel note right of card Fragment réutilisable pour afficher une carte de projet avec : - thumbnail - titre - tags - highlights end note @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_데이터_추출_패턴">데이터 추출 패턴</h3> <div class="paragraph"> <p>JBake은 AsciiDoc 속성을 자동으로 Thymeleaf에서 접근 가능한 속성으로 변환합니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE rectangle "문서 AsciiDoc" { (":project-client: 애크미 코퍼레이션") as attr1 (":project-duration: 6개월") as attr2 (":project-tags: java, react") as attr3 } rectangle "JBake 모델" { (content['project-client']) as prop1 (content['project-duration']) as prop2 (content.tags) as prop3 } rectangle "템플릿 Thymeleaf" { (th:text="${project['project-client']}") as tmpl1 (th:text="${project['project-duration']}") as tmpl2 (th:each="태그 : ${project.tags}") as tmpl3 } attr1 --> prop1 : parsing attr2 --> prop2 : parsing attr3 --> prop3 : parsing prop1 --> tmpl1 : binding prop2 --> tmpl2 : binding prop3 --> tmpl3 : binding @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_명명_규칙">명명 규칙</h3> <div class="ulist"> <ul> <li> <p><strong>프로젝트 속성</strong> : 접두사`project-*` (ex: <code>project-client</code>, <code>project-tech-stack</code>)</p> </li> <li> <p><strong>파일</strong> : kebab-case (예:`ecommerce-platform.adoc`)</p> </li> <li> <p><strong>Images</strong> : 프로젝트 이름 접두사 (예:`ecommerce-platform-thumb.jpg`)</p> </li> <li> <p><strong>Templates</strong> : 기능적 이름 (예:`project-card.html`, <code>tech-badge.html</code>)</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_출판_워크플로우">출판 워크플로우</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_개발_파이프라인">개발 파이프라인</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam handwritten false class ProjetAsciiDoc { +titre: String +jbake-type: "프로젝트" +jbake-status: published|draft +jbake-date: Date +jbake-tags: List<String> __ +project-category: String +project-client: String +project-duration: String +project-role: String +project-thumbnail: String +project-gallery: List<String> +project-tech-stack: String +project-highlights: List<String> +project-demo-url: String +project-github-url: String __ +body: HTML (converti) } class JBakeEngine { +parse(asciidoc) +extractMetadata() +convertToHTML() } class ThymeleafTemplate { +portfolio.html +project.html +partials/project-card.html } class PortfolioPage { +published_projects: List +filtres: categories } ProjetAsciiDoc --> JBakeEngine : parse JBakeEngine --> ThymeleafTemplate : fournit données ThymeleafTemplate --> PortfolioPage : génère @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_환경">환경</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 20%;"> <col style="width: 40%;"> <col style="width: 40%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">환경</th> <th class="tableblock halign-left valign-top">사용</th> <th class="tableblock halign-left valign-top">수락된 상태</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">로컬</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">개발 및 미리보기</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">초안, 게시됨</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">스테이징</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">사전 제작 검증</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">게시된 것만</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">생산</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">공공 사이트</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">단독으로 게시됨</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_확장성">확장성</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_새로운_속성_추가">새로운 속성 추가</h3> <div class="paragraph"> <p>데이터 모델을 풍부하게 하기 위해, 단순히 새로운 접두사가 붙은 속성을 추가하면 됩니다.<code>project-*</code>[No output]</p> </div> <div class="ulist"> <ul> <li> <p><code>project-awards</code>: 수상 및 인정</p> </li> <li> <p>`project-testimonial`고객 인용</p> </li> <li> <p>`project-team-size`팀 규모</p> </li> <li> <p><code>project-budget-range</code>: 예산 범위</p> </li> </ul> </div> <div class="paragraph"> <p>이러한 속성은 JBake 엔진을 수정하지 않고도 템플릿에서 자동으로 사용할 수 있게 됩니다.</p> </div> </div> <div class="sect2"> <h3 id="_고급_분류">고급 분류</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE object Projet { project-category = "웹" project-subcategory = "전자상거래" project-industry = "소매" project-complexity = "높은" } object Taxonomie { categories : [web, mobile, data, devops] subcategories : Map<category, List> industries : [retail, finance, healthcare, ...] complexities : [low, medium, high] } Projet --> Taxonomie : classifié selon note right of Taxonomie Permet filtrage multi-critères dans le template portfolio.html via JavaScript ou côté serveur end note @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_모범_사례">모범 사례</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_파일_구성">파일 구성</h3> <div class="ulist"> <ul> <li> <p><strong>파일 하나 = 프로젝트 하나</strong> : 여러 프로젝트를 섞지 않도록 피하다</p> </li> <li> <p><strong>전용 폴더의 이미지</strong> :`assets/img/portfolio/nom-projet/`</p> </li> <li> <p><strong>일관된 명명법</strong> : 검색과 유지보수가 쉬워집니다</p> </li> <li> <p><strong>Versioning Git</strong> : 수정된 사항의 완전한 추적</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_콘텐츠_관리">콘텐츠 관리</h3> <div class="ulist"> <ul> <li> <p><strong>기본 초안 상태</strong> : 준비됐을 때만 게시</p> </li> <li> <p><strong>출판 전 검토</strong> : 품질 및 기밀성 검증</p> </li> <li> <p><strong>완전한 메타데이터</strong> : 모든 관련 필드를 채우세요</p> </li> <li> <p><strong>풍부한 서사 내용</strong> : 메타데이터에만 국한되지 마라</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_성능">성능</h3> <div class="ulist"> <ul> <li> <p><strong>이미지 최적화</strong> : 커밋 전 압축</p> </li> <li> <p><strong>필요한 경우 페이지네이션</strong> : 프로젝트가 20개 이상이면</p> </li> <li> <p><strong>Lazy loading</strong> : 갤러리 이미지 필요 시 로드</p> </li> <li> <p><strong>브라우저 캐시</strong> : 자산에 대한 적절한 헤더</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_결론">결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 아키텍처는 다음을 허용합니다 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>간편함</strong> : 프로젝트 추가 = 텍스트 파일 만들기</p> </li> <li> <p><strong>유연성</strong> : 새로운 속성을 통해 확장 가능</p> </li> <li> <p><strong>유지보수성</strong> : 내용과 표현의 분리</p> </li> <li> <p><strong>추적성</strong> : 완전한 Git 버전 관리</p> </li> <li> <p><strong>Automatisation</strong> : 빌드 및 연속적인 배포가 가능</p> </li> </ul> </div> <div class="paragraph"> <p>AsciiDoc 선택은 사이트의 나머지와 일관성을 유지하면서 전문 포트폴리오에 필요한 풍부한 메타데이터를 제공한다.</p> </div> </div> </div> https://cheroliv.com/blog/pilot-batch/0100_jbake_supabase_springboot_hybride_post.html Wed, 14 Jan 2026 00:00:00 +0000 blog/pilot-batch/0100_jbake_supabase_springboot_hybride_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽기 시간 : 12 minutes</div> <p>Supabase의 간결함과 Spring Boot의 강력함 사이에서 선택하기보다 왜 두 가지를 결합하지 않을까요? 각 기술의 장점을 활용하는 하이브리드 아키텍처를 살펴보세요.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">똑</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_현대_건축의_가짜_딜레마">현대 건축의 가짜 딜레마</h2> <div class="sectionbody"> <div class="paragraph"> <p>정적 프론트엔드를 사용해 현대적인 애플리케이션을 구축할 때, 종종 이진 선택에 직면하게 됩니다 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>백엔드-어즈-어-서비스 솔루션에 모든 것을 걸다</strong>(Supabase, Firebase) - 간단하지만 제한적</p> </li> <li> <p><strong>전체 백엔드 구축하기</strong>(Spring Boot, Node.js) - 강력하지만 복잡한</p> </li> </ul> </div> <div class="paragraph"> <p>이 선택은 가짜 딜레마입니다. 하이브리드 아키텍처는 세 번째 길을 제시합니다: <strong>각 기술을 그들이 가장 잘하는 곳에 사용하는 것</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_건축_비전">건축 비전</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_전통적인_건축_일체형">전통적인 건축: 일체형</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "전통적인 건축" { actor Utilisateur as user component "프론트엔드" as frontend #LightBlue component "모놀리식 백엔드" as backend #LightCoral { [Authentification] [CRUD] [Logique Métier] [Jobs] [APIs Tierces] } database "데이터베이스" as db #LightGray user --> frontend frontend --> backend : Toutes les requêtes backend --> db } note right of backend Tout passe par le backend même les opérations simples ⚠️ Point de congestion unique ⚠️ Complexité dès le départ ⚠️ Couplage fort end note @enduml</pre> </div> </div> <div class="paragraph"> <p>이 접근 방식에서는 가장 간단한 작업(글 읽기, 댓글 작성)이라 할지라도 백엔드를 경유해야 하며, 첫날부터 복잡성의 비용을 지불하게 됩니다.</p> </div> </div> <div class="sect2"> <h3 id="_baas_아키텍처_모든_대리자">BaaS 아키텍처: 모든 대리자</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "순수 BaaS 아키텍처" { actor Utilisateur as user component "프론트엔드" as frontend #LightBlue cloud "Supabase / Firebase" as baas #LightGreen { [Auth] [Database] [Storage] [Edge Functions] } user --> frontend frontend --> baas : Toutes les opérations } note right of baas Développement rapide Pas de serveur à gérer ⚠️ Limité pour logique complexe ⚠️ Vendor lock-in ⚠️ Edge Functions contraintes end note @enduml</pre> </div> </div> <div class="paragraph"> <p>반면에, BaaS에 모든 것을 위임하는 것은 처음에는 매력적이지만, 비즈니스 로직이 복잡해지면 곧 한계가 드러납니다.</p> </div> </div> <div class="sect2"> <h3 id="_하이브리드_아키텍처_책임_분리">하이브리드 아키텍처 : 책임 분리</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle actor Utilisateur as user #LightBlue package "프론트엔드 레이어" { component "정적 사이트 JBake" as frontend #SkyBlue } package "단순 레이어 (Supabase)" #LightGreen { component "인증" as auth component "CRUD 기본" as crud component "파일 저장" as storage component "실시간" as realtime } package "비즈니스 계층 (Spring Boot)" #Coral { component "복잡한 논리" as logic component "편곡" as orchestration component "예약된 작업" as jobs component "통합" as integrations } database "PostgreSQL 공유" as db #LightGray user --> frontend frontend --> auth : OAuth2, JWT frontend --> crud : Articles, Profils frontend --> storage : Images, Fichiers frontend --> realtime : Notifications frontend --> logic : Calculs, Rapports frontend --> orchestration : Workflows logic --> integrations : Stripe, APIs orchestration --> db jobs --> db crud --> db auth --> db note bottom of db **Une seule source de vérité** Partagée entre Supabase et Spring Boot end note note right of auth **Gratuit jusqu'à 50k users** Configuration en quelques clics OAuth2 multi-providers end note note right of logic **Activé seulement si nécessaire** Kotlin + Coroutines Transactions complexes end note @enduml</pre> </div> </div> <div class="paragraph"> <p>하이브리드 아키텍처는 복잡성과 운영의 특성에 따라 책임을 명확히 분리한다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_디자인_원칙">디자인 원칙</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_원칙_1_간단히_시작하고_지능적으로_발전하기">원칙 1: 간단히 시작하고, 지능적으로 발전하기</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE rectangle "1단계 : MVP" #LightGreen { component "JBake + Supabase" as mvp note right ✓ Développement en jours ✓ Coût : 0€ ✓ Validation concept end note } rectangle "**2단계 : 성장**" #LightYellow { component "JBake + Supabase + Spring Boot (옵션)" as growth note right ✓ Logique métier émerge ✓ Premiers jobs planifiés ✓ Intégrations tierces end note } rectangle "**3단계 : 확대**" #LightCoral { component "완전한 아키텍처" as scale note right ✓ Orchestration complexe ✓ Performances optimisées ✓ Cache distribué end note } mvp -down-> growth : Quand la complexité\nle justifie growth -down-> scale : Optimisation\ncontinue @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>필요하지 않다면 Spring Boot을 구축하지 마세요.</strong>Supabase로 시작하고, 복잡성이 이를 정당화할 때 Spring Boot를 추가하세요.</p> </div> </div> <div class="sect2"> <h3 id="_원칙_2_작업의_성격에_따른_분리">원칙 2: 작업의 성격에 따른 분리</h3> <div class="listingblock"> <div class="content"> <pre>@startmindmap skinparam backgroundColor #FEFEFE * Opérations\nApplicatives left side ** Opérations Simples\n(Supabase) ***_ CRUD Standard ****_ Lecture ****_ Création ****_ Mise à jour ****_ Suppression ***_ Authentification ****_ Login/Logout ****_ OAuth2 ****_ Gestion session ***_ Stockage ****_ Upload fichiers ****_ CDN automatique ***_ Temps Réel ****_ WebSocket ****_ Notifications right side ** Opérations Complexes\n(Spring Boot) ***_ Logique Métier ****_ Calculs complexes ****_ Règles métier ****_ Validations avancées ***_ Orchestration ****_ Multi-services ****_ Transactions distribuées ****_ Saga patterns ***_ Tâches Planifiées ****_ Rapports périodiques ****_ Synchronisations ****_ Nettoyages ***_ Intégrations ****_ Paiements (Stripe) ****_ APIs tierces ****_ Services ML/AI @endmindmap</pre> </div> </div> </div> <div class="sect2"> <h3 id="_원칙_3_단_하나의_진실의_원천">원칙 3 : 단 하나의 진실의 원천</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE database "PostgreSQL" as db #LightGray { package "스키마: auth (Supabase)" #LightGreen { [users] [sessions] [identities] } package "스키마: 공개 (공유)" #SkyBlue { [articles] [comments] [profiles] } package "스키마: 비즈니스 (Spring Boot)" #Coral { [orders] [payments] [reports] } } component "수퍼베이스" as supabase #LightGreen component "스프링 부트" as spring #Coral supabase -down-> users : Gère supabase -down-> sessions : Gère supabase -down-> articles : Accède supabase -down-> comments : Accède supabase -down-> profiles : Accède spring -down-> articles : Accède spring -down-> profiles : Accède spring -down-> orders : Gère spring -down-> payments : Gère spring -down-> reports : Gère note right of db **Avantages :** • Pas de synchronisation complexe • JOINs possibles entre tables • Cohérence garantie • Migrations unifiées end note @enduml</pre> </div> </div> <div class="paragraph"> <p>PostgreSQL 동일한 인스턴스를 공유함으로써, Supabase와 Spring Boot는 복잡한 동기화 없이 동일한 데이터에서 작업합니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_흐름_오케스트레이션">흐름 오케스트레이션</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_플럭스_1_중앙_집중식_인증">플럭스 1 : 중앙 집중식 인증</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE autonumber actor "사용자" as user participant "JBake" as jbake participant "Supabase Auth" as auth participant "스프링 부트" as spring database "PostgreSQL" as db == Authentification == user -> jbake : Clique "로그인" jbake -> auth : Redirect OAuth2 (Google/GitHub) auth -> user : Consent screen user -> auth : Autorise auth -> auth : Génère JWT auth -> jbake : Retourne JWT + Refresh Token jbake -> jbake : Stocke tokens (sessionStorage) == Accès aux Ressources == group Opération Simple (CRUD) user -> jbake : Crée un article jbake -> db : POST avec JWT note right: Supabase Row Level Security\nvérifie le JWT automatiquement db -> jbake : Article créé end group Opération Complexe (Métier) user -> jbake : Génère un rapport jbake -> spring : POST /api/reports\navec JWT spring -> spring : Valide JWT Supabase spring -> spring : Extrait claims (user_id, roles) spring -> db : Requêtes complexes spring -> jbake : Rapport généré end note over auth, spring **Le JWT est universel** Valide par Supabase ET Spring Boot Pas de double authentification end note @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>핵심 포인트</strong>: 하나의 인증 프로세스, 하나의 JWT, 어디에서나 사용 가능.</p> </div> </div> <div class="sect2"> <h3 id="_플럭스_2_복잡한_비즈니스_프로세스의_오케스트레이션">플럭스 2 : 복잡한 비즈니스 프로세스의 오케스트레이션</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE autonumber actor "클라이언트" as user participant "JBake" as jbake participant "스프링 부트" as spring participant "Supabase DB" as supadb participant "스트라이프 API" as stripe participant "재고 서비스" as inventory participant "이메일 서비스" as email database "PostgreSQL" as db user -> jbake : Passe commande jbake -> spring : POST /api/orders/create == Orchestration Spring Boot == spring -> db : BEGIN TRANSACTION par Vérifications Parallèles spring -> inventory : Vérifier stock inventory -> spring : Stock OK else spring -> db : Vérifier profil client db -> spring : Client vérifié end spring -> stripe : Créer Payment Intent stripe -> spring : Intent créé (ID: pi_xxx) spring -> db : Créer Order (status: PENDING) db -> spring : Order créé spring -> stripe : Confirmer paiement stripe -> spring : Paiement confirmé spring -> db : Update Order (status: PAID) spring -> inventory : Décrémenter stock spring -> db : COMMIT TRANSACTION par Notifications Asynchrones spring -> email : Email confirmation else spring -> supadb : Insert notification note right: Notification temps réel\nvia Supabase Realtime end spring -> jbake : Order confirmé jbake -> user : Affiche confirmation note over spring **Responsabilités Spring Boot :** • Transaction ACID • Orchestration multi-services • Rollback automatique si erreur • Gestion des cas limites end note @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>Spring Boot가 제공하는 것</strong>: 여러 시스템을 포함하는 복잡한 프로세스의 신뢰할 수 있는 오케스트레이션, 트랜잭션 보장과 함께.</p> </div> </div> <div class="sect2"> <h3 id="_flux_3_예약된_작업_및_동기화">Flux 3 : 예약된 작업 및 동기화</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE participant "스케줄러\n(Spring Boot)" as scheduler participant "리포트 서비스" as report participant "PostgreSQL" as db participant "외부 API" as api participant "이메일 서비스" as email participant "Supabase 스토리지" as storage == Job Quotidien : 2h00 == activate scheduler scheduler -> report : Déclenche génération rapport activate report report -> db : Récupère données\ndes dernières 24h db -> report : Dataset report -> report : Calculs & Agrégations report -> report : Génération PDF report -> storage : Upload PDF storage -> report : URL publique report -> email : Envoie aux admins\navec lien PDF deactivate report == Job Hebdomadaire : Dimanche 3h00 == scheduler -> report : Synchronisation externe activate report report -> api : Fetch données externes api -> report : Nouvelles données report -> db : Mise à jour tables report -> db : Nettoyage données obsolètes deactivate report == Job Mensuel : 1er du mois == scheduler -> report : Facturation activate report report -> db : Liste clients actifs report -> report : Calcul montants report -> api : Génération factures (Stripe) report -> email : Envoi factures deactivate report deactivate scheduler note right of scheduler **Impossible avec Supabase seul** Edge Functions non adaptées pour jobs longs et récurrents end note @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>Spring Boot가 제공하는 것</strong>: 상태 관리, 자동 재시도, 보장된 실행을 제공하는 신뢰할 수 있는 예약 작업</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_의사결정_매트릭스">의사결정 매트릭스</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_supabase를_언제_사용해야_하나요">Supabase를 언제 사용해야 하나요?</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE start :Nouvelle fonctionnalité à implémenter; if (CRUD simple ?) then (oui) :✅ **Supabase**; stop else (non) if (Authentification ?) then (oui) :✅ **Supabase Auth**; stop else (non) if (Upload fichiers ?) then (oui) :✅ **Supabase Storage**; stop else (non) if (Temps réel ?) then (oui) :✅ **Supabase Realtime**; stop else (non) if (Row Level Security\nsuffisante ?) then (oui) :✅ **Supabase + Policies**; stop else (non) :⚠️ **Considérer Spring Boot**; #Coral:Passer à l'arbre\nde décision Spring Boot; stop endif endif endif endif endif @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_spring_boot은_언제_사용해야_하나요">Spring Boot은 언제 사용해야 하나요?</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE start :Nouvelle fonctionnalité complexe; if (Orchestration\nmulti-services ?) then (oui) :✅ **Spring Boot**; stop else (non) if (Transaction ACID\ncritique ?) then (oui) :✅ **Spring Boot**; stop else (non) if (Job planifié ?) then (oui) :✅ **Spring Boot Scheduler**; stop else (non) if (Intégration API\ntierce complexe ?) then (oui) :✅ **Spring Boot**; stop else (non) if (Calculs lourds\n> 10 secondes ?) then (oui) :✅ **Spring Boot**; stop else (non) if (Cache distribué\nnécessaire ?) then (oui) :✅ **Spring Boot + Redis**; stop else (non) :⚠️ **Probablement Supabase**; #LightGreen:Revenir à l'arbre\nde décision Supabase; stop endif endif endif endif endif endif @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_프로젝트_유형별_건축_예시">프로젝트 유형별 건축 예시</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_블로그_포트폴리오">블로그 / 포트폴리오</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "개인 블로그 - 95% Supabase" { component "JBake" as jbake #SkyBlue package "Supabase (무료)" #LightGreen { [Auth: OAuth2 Google] [Articles (CRUD)] [Commentaires] [Images (Storage)] [Notifications Realtime] } package "Spring Boot (선택 사항)" #LightCoral { [Newsletter Mensuelle] note bottom: Job planifié uniquement } database "PostgreSQL" as db jbake --> [Auth: OAuth2 Google] jbake --> [Articles (CRUD)] jbake --> [Commentaires] jbake --> [Images (Storage)] jbake --> [Notifications Realtime] [Articles (CRUD)] --> db [Commentaires] --> db [Newsletter Mensuelle] --> db } note bottom of "Spring Boot (선택 사항)" **Spring Boot pas obligatoire** Newsletter peut être gérée par un service tiers (Mailchimp) end note @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>판결</strong>: 100% Supabase면 충분합니다.</p> </div> </div> <div class="sect2"> <h3 id="_saas_애플리케이션">SaaS 애플리케이션</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "SaaS 애플리케이션 - 하이브리드 아키텍처" { component "JBake / React" as frontend #SkyBlue package "Supabase" #LightGreen { [Auth Multi-tenant] [Profils Utilisateurs] [Données Simples] [Storage Documents] } package "스프링 부트" #Coral { [Facturation (Stripe)] [Analytics Avancées] [Rapports Mensuels] [Quotas & Limites] [Webhooks Stripe] } cloud "외부 서비스" { [Stripe API] [SendGrid Email] } database "공유된 PostgreSQL" as db frontend --> [Auth Multi-tenant] frontend --> [Profils Utilisateurs] frontend --> [Données Simples] frontend --> [Facturation (Stripe)] frontend --> [Analytics Avancées] [Auth Multi-tenant] --> db [Profils Utilisateurs] --> db [Données Simples] --> db [Facturation (Stripe)] --> db [Facturation (Stripe)] --> [Stripe API] [Analytics Avancées] --> db [Rapports Mensuels] --> db [Rapports Mensuels] --> [SendGrid Email] [Webhooks Stripe] ..> [Stripe API] : Écoute } note right of "스프링 부트" **Nécessaire pour :** • Gestion abonnements • Facturation récurrente • Quotas dynamiques • Analytics complexes • Webhooks fiables end note @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>평결</strong>: 필요한 하이브리드 아키텍처. Supabase는 주로 사용하고, Spring Boot는 중요한 부분(결제, 청구)에 사용합니다.</p> </div> </div> <div class="sect2"> <h3 id="_전자상거래">전자상거래</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "전자상거래 - 70% Spring Boot" { component "스토어프론트 (JBake/React)" as frontend #SkyBlue package "Supabase" #LightGreen { [Auth Clients] [Catalogue Produits\n(lecture seule)] [Images Produits] } package "Spring Boot (핵심 비즈니스)" #Coral { [Gestion Commandes] [Paiements Stripe] [Gestion Stock] [Calcul Frais Port] [Génération Factures] [Synchronisation ERP] [Emails Transactionnels] } cloud "통합" { [Stripe] [Transporteur API] [ERP Externe] } database "PostgreSQL" as db frontend --> [Auth Clients] frontend --> [Catalogue Produits\n(lecture seule)] frontend --> [Gestion Commandes] [Auth Clients] --> db [Catalogue Produits\n(lecture seule)] --> db [Gestion Commandes] --> db [Paiements Stripe] --> [Stripe] [Gestion Stock] --> db [Calcul Frais Port] --> [Transporteur API] [Génération Factures] --> db [Synchronisation ERP] --> [ERP Externe] [Synchronisation ERP] --> db } note right of "Spring Boot (핵심 비즈니스)" **Spring Boot indispensable :** • Transactions critiques • Orchestration complexe • Intégrations multiples • Conformité légale • Jobs de synchronisation end note @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>판결</strong>Spring Boot 필수적입니다. Supabase는 인증 및 카탈로그용으로만 사용합니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_점진적_마이그레이션_전략">점진적 마이그레이션 전략</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE |Semaine 1-2| start :Créer projet Supabase; :Configurer Auth (Google, GitHub); :Définir schéma PostgreSQL initial; :Implémenter CRUD de base sur JBake; :Déployer MVP sur GitHub Pages; note right **Livrable :** Application fonctionnelle **Coût :** 0€ **Temps :** 1-2 semaines end note |Semaine 3-4| :Observer utilisation réelle; :Identifier limitations; |Décision| if (Logique complexe\némerge ?) then (non) |Supabase| :Continuer avec Supabase seul; :Ajouter Edge Functions si besoin; stop else (oui) |Spring Boot| :Créer projet Spring Boot; :Configurer validation JWT Supabase; :Migrer logique complexe vers Spring Boot; note right **Migration sélective** Seulement ce qui est complexe end note endif |Semaines suivantes| :Déployer Spring Boot (Cloud Run, EC2); :Connecter à PostgreSQL Supabase; :Implémenter premiers jobs planifiés; :Intégrer APIs tierces; stop note right **Architecture finale hybride** Supabase + Spring Boot en parfaite harmonie end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_비용_및_운영_고려_사항">비용 및 운영 고려 사항</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_비용_구조">비용 구조</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE package "예상 월간 비용" { rectangle "MVP 단계 (0-1000 사용자)" #LightGreen { [JBake (GitHub Pages): 0€] [Supabase: 0€] [Spring Boot: N/A] note bottom: **Total: 0€/mois** } rectangle "성장 단계 (1k-10k 사용자)" #LightYellow { [JBake (GitHub Pages): 0€] [Supabase: 0€] [Spring Boot (Cloud Run): 20-50€] [PostgreSQL (si séparé): 0-30€] note bottom: **Total: 20-80€/mois** } rectangle "단계 규모 (10k-100k 사용자)" #LightCoral { [JBake (Netlify Pro): 19€] [Supabase Pro: 25€] [Spring Boot (instances multiples): 100-300€] [Redis Cache: 20-50€] [Monitoring: 20€] note bottom: **Total: 184-414€/mois** } } note right of "단계 규모 (10k-100k 사용자)" À ce stade, les revenus justifient largement les coûts end note @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_운영_책임">운영 책임</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE package "누가 무엇을 관리하나요?" { rectangle "Supabase에서 관리 (0 노력)" #LightGreen { [Authentification] [Base de données] [Backups automatiques] [Scaling automatique] [Monitoring DB] [Sécurité DB] } rectangle "GitHub에서 관리 (노력 없음)" #SkyBlue { [Hébergement site statique] [HTTPS/SSL] [CDN global] [Déploiement automatique] } rectangle "관리 (Spring Boot)" #LightCoral { [Déploiement application] [Monitoring APM] [Logs centralisés] [Scaling horizontal] [Mises à jour sécurité] } } note bottom of "관리 (Spring Boot)" **Minimisable avec :** • Cloud Run (serverless) • Kubernetes (si nécessaire) • Services managés (RDS, etc.) end note @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_결론_완벽한_균형">결론 : 완벽한 균형</h2> <div class="sectionbody"> <div class="paragraph"> <p>Supabase + Spring Boot 하이브리드 아키텍처는 타협이 아니라, 이것은<strong>시너지</strong>.</p> </div> <div class="sect2"> <h3 id="_기억해야_할_원칙">기억해야 할 원칙</h3> <div class="listingblock"> <div class="content"> <pre>@startmindmap skinparam backgroundColor #FEFEFE * Architecture\nHybride ** Commencer Simple ***_ MVP avec Supabase ***_ 0€ de coût initial ***_ Validation rapide ** Évoluer Intelligemment ***_ Ajouter Spring Boot\nsi nécessaire ***_ Migration progressive ***_ Pas de refonte totale ** Exploiter les Forces ***_ Supabase: Simplicité ***_ Spring Boot: Puissance ***_ PostgreSQL: Source unique ** Minimiser la Complexité ***_ Pas de synchronisation ***_ Pas de duplication ***_ Architecture claire ** Optimiser les Coûts ***_ Gratuit au départ ***_ Scaling progressif ***_ ROI évident @endmindmap</pre> </div> </div> </div> <div class="sect2"> <h3 id="_이_아키텍처를_언제_선택해야_할까요">이 아키텍처를 언제 선택해야 할까요?</h3> <div class="paragraph"> <p><strong>✅ 이 아키텍처는 다음 경우에 이상적입니다 :</strong></p> </div> <div class="ulist"> <ul> <li> <p>당신은 빠르게 시작하고 싶으신가요 (몇 달이 아닌 며칠 안에 MVP를 구현하고 싶으신가요)</p> </li> <li> <p>당신은 비즈니스 복잡성의 성장을 예상합니다.</p> </li> <li> <p>당신은 초기 비용을 최소화하고 싶습니다.</p> </li> <li> <p>PostgreSQL을 좋아하고 단일한 진실의 출처를 원합니다.</p> </li> <li> <p>당신은 비즈니스 코드를 위해 Kotlin과 코루틴을 좋아합니다</p> </li> <li> <p>완전한 벤더 락인을 피하고 싶어요</p> </li> </ul> </div> <div class="paragraph"> <p><strong>❌ 이 아키텍처는 적합하지 않으면:</strong></p> </div> <div class="ulist"> <ul> <li> <p>당신의 프로젝트는 간단하고 그대로 유지될 것입니다 (개인 블로그 → 100% Supabase면 충분합니다)</p> </li> <li> <p>당신은 이미 확립된 백엔드 스택을 잘 알고 있습니다</p> </li> <li> <p>전통적인 모노리스를 선호합니다.</p> </li> <li> <p>.NET, Python 또는 백엔드 측 언어가 필요합니다</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_최종_전체_비전">최종 전체 비전</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE package "완전한 하이브리드 아키텍처" { actor "사용자" as users rectangle "프론트엔드 (정적)" #SkyBlue { [JBake / GitHub Pages] note right: Gratuit, CDN global } rectangle "백엔드 간단 (Supabase)" #LightGreen { [Auth OAuth2] [CRUD APIs] [Storage] [Realtime] note right Gratuit jusqu'à 50k users Zéro configuration serveur end note } rectangle "비즈니스 백엔드 (Spring Boot)" #Coral { [Orchestration] [Jobs Planifiés] [Intégrations] [Transactions] note right Activé uniquement si nécessaire end note } database "PostgreSQL 단일 진실의 출처" as db #LightGray users --> [JBake / GitHub Pages] [JBake / GitHub Pages] --> [Auth OAuth2] [JBake / GitHub Pages] --> [CRUD APIs] [JBake / GitHub Pages] --> [Storage] [JBake / GitHub Pages] --> [Realtime] [JBake / GitHub Pages] --> [Orchestration] [Auth OAuth2] --> db [CRUD APIs] --> db [Orchestration] --> db [Jobs Planifiés] --> db [Intégrations] --> db } note bottom of db **Une seule base, deux consommateurs** • Supabase pour le simple • Spring Boot pour le complexe • Aucune synchronisation requise end note @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_양쪽의_최고">양쪽의 최고</h3> <div class="paragraph"> <p>이 아키텍처는 당신에게 다음을 제공합니다:</p> </div> <div class="paragraph"> <p><strong>🚀 Supabase의 속도</strong></p> </div> <div class="ulist"> <ul> <li> <p>시작은 시간 단위로, 주 단위가 아니다.</p> </li> <li> <p>몇 클릭만으로 OAuth2 인증</p> </li> <li> <p>자동으로 생성된 REST API</p> </li> <li> <p>서버 무설정</p> </li> </ul> </div> <div class="paragraph"> <p><strong>💪 Spring Boot의 힘</strong></p> </div> <div class="ulist"> <ul> <li> <p>우아한 비동기 코드를 위한 Kotlin과 Coroutines</p> </li> <li> <p>복잡한 비즈니스 프로세스 오케스트레이션</p> </li> <li> <p>신뢰할 수 있는 예약된 작업</p> </li> <li> <p>보장된 ACID 트랜잭션</p> </li> <li> <p>완전한 Spring 생태계</p> </li> </ul> </div> <div class="paragraph"> <p><strong>💰 진보적인 경제</strong></p> </div> <div class="ulist"> <ul> <li> <p>0€로 시작하고 확인</p> </li> <li> <p>성장에 따르는 비용</p> </li> <li> <p>조기 과설계 없음</p> </li> </ul> </div> <div class="paragraph"> <p><strong>🎯 건축적 유연성</strong></p> </div> <div class="ulist"> <ul> <li> <p>점진적 마이그레이션, 개편 없이</p> </li> <li> <p>필요한 경우에만 Spring Boot 추가</p> </li> <li> <p>완전한 벤더 락인 없음</p> </li> <li> <p>변화 가능한 아키텍처</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_더_나아가기">더 나아가기</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_기술_자원">기술 자원</h3> <div class="paragraph"> <p><strong>Supabase 문서 :</strong></p> </div> <div class="ulist"> <ul> <li> <p><a href="https://supabase.com/docs/guides/auth">인증 가이드</a></p> </li> <li> <p><a href="https://supabase.com/docs/guides/database/postgres/row-level-security">행 수준 보안</a></p> </li> <li> <p><a href="https://supabase.com/docs/guides/api">자동 생성된 API</a></p> </li> </ul> </div> <div class="paragraph"> <p><strong>Spring Boot 문서 :</strong></p> </div> <div class="ulist"> <ul> <li> <p><a href="https://spring.io/guides/tutorials/spring-boot-kotlin/">Spring Boot와 Kotlin</a></p> </li> <li> <p><a href="https://spring.io/blog/2019/04/12/going-reactive-with-spring-coroutines-and-kotlin-flow">코루틴과 스프링</a></p> </li> <li> <p><a href="https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html">JWT 리소스 서버</a></p> </li> </ul> </div> <div class="paragraph"> <p><strong>부칙:</strong></p> </div> <div class="ulist"> <ul> <li> <p>JWT를 사용한 API 보안</p> </li> <li> <p>PostgreSQL 성능 최적화</p> </li> <li> <p>점진적인 마이그레이션 패턴</p> </li> <li> <p>분산 아키텍처에서의 오류 관리</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_실제_사용_사례">실제 사용 사례</h3> <div class="paragraph"> <p>이 하이브리드 아키텍처는 다음에서 성공적으로 사용됩니다 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>B2B SaaS</strong>: Supabase 인증, Spring Boot 청구</p> </li> <li> <p><strong>마켓플레이스</strong>Supabase 카탈로그, Spring Boot 트랜잭션</p> </li> <li> <p><strong>콘텐츠 플랫폼</strong>: Supabase 문서, Spring Boot 분석</p> </li> <li> <p><strong>내부 도구</strong>: CRUD Supabase, 워크플로우 Spring Boot</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_시작_체크리스트">시작 체크리스트</h3> <div class="paragraph"> <p><strong>Phase 1 - 기초 (1주차)</strong></p> </div> <div class="ulist checklist"> <ul class="checklist"> <li> <p><i class="fa fa-square-o"></i> Supabase 계정 만들기 - [ ] PostgreSQL 프로젝트 구성 - [ ] 인증 활성화 (Google, GitHub) - [ ] 초기 스키마 정의 - [ ] 구성 Row Level Security - [ ] JBake에서 API 테스트</p> </li> </ul> </div> <div class="paragraph"> <p><strong>2단계 - MVP (2-3주)</strong></p> </div> <div class="ulist checklist"> <ul class="checklist"> <li> <p><i class="fa fa-square-o"></i> 메인 페이지 구현 - [ ] OAuth2 인증 통합 - [ ] CRUD 폼 생성 - [ ] Storage를 파일용으로 구성 - [ ] GitHub Pages에 배포 - [ ] 실제 조건에서 테스트하기</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Phase 3 - 진화 (필요에 따라)</strong></p> </div> <div class="ulist checklist"> <ul class="checklist"> <li> <p><i class="fa fa-square-o"></i> 복잡한 논리 요구 사항 식별 - [ ] 필요하면 Spring Boot 프로젝트를 생성 - [ ] Supabase JWT 검증 구성 - [ ] PostgreSQL Supabase에 연결 - [ ] 복잡한 기능 마이그레이션 - [ ] 예정된 작업 구현 - [ ] Spring Boot 배포 (Cloud Run 등)</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_피해야_할_안티패턴">피해야 할 안티패턴</h3> <div class="paragraph"> <p><strong>❌ 하지 말 것 :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Supabase와 Spring Boot 사이의 데이터 복제</p> </li> <li> <p>두 개의 별도 PostgreSQL 데이터베이스 생성</p> </li> <li> <p>인증을 직접 코딩하세요</p> </li> <li> <p>Spring Boot를 이용해 간단한 CRUD</p> </li> <li> <p>초기부터 과도하게 설계하다</p> </li> <li> <p>Supabase의 Row Level Security 무시하기</p> </li> </ul> </div> <div class="paragraph"> <p><strong>✅ 더 하다:</strong></p> </div> <div class="ulist"> <ul> <li> <p>단 하나의 PostgreSQL 데이터베이스 공유</p> </li> <li> <p>Supabase가 인증을 관리하도록 두세요</p> </li> <li> <p>복잡함을 위해서만 Spring Boot을 사용</p> </li> <li> <p>간단히 시작하고 점차 발전하다</p> </li> <li> <p>각 기술의 강점을 활용</p> </li> <li> <p>데이터베이스 수준에서 RLS로 보안 강화하기</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_발전_전망">발전 전망</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_새로운_기능_추가">새로운 기능 추가</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE rectangle "현재 아키텍처" #SkyBlue { [JBake] [Supabase] [Spring Boot] } rectangle "가능한 변화" #LightYellow { package "성능" { [Redis Cache] [CDN pour Assets] [PostgreSQL Replicas] } package "모니터링" { [Grafana] [Prometheus] [Sentry] } package "지속적 통합/지속적 배포" { [GitHub Actions] [Tests Automatisés] [Déploiement Continu] } package "기능" { [Search (ElasticSearch)] [Queue (RabbitMQ)] [Event Sourcing] } } [Spring Boot] .down.> [Redis Cache] : Peut ajouter [Spring Boot] .down.> [Queue (RabbitMQ)] : Peut ajouter [Spring Boot] .down.> [Search (ElasticSearch)] : Peut ajouter [Supabase] .down.> [PostgreSQL Replicas] : Peut ajouter note bottom **Architecture extensible** Chaque ajout est indépendant Pas de refonte globale nécessaire end note @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_수평_확장">수평 확장</h3> <div class="paragraph"> <p>앱이 성장함에 따라 하이브리드 아키텍처는 자연스럽게 확장됩니다 :</p> </div> <div class="paragraph"> <p><strong>Supabase:</strong></p> </div> <div class="ulist"> <ul> <li> <p>자동으로 수백만 건의 작업까지 확장</p> </li> <li> <p>읽기 성능을 위한 읽기 복제본</p> </li> <li> <p>시점 기반 복구 (보안)</p> </li> </ul> </div> <div class="paragraph"> <p><strong>스프링 부트 :</strong></p> </div> <div class="ulist"> <ul> <li> <p>로드 밸런서 뒤에 여러 인스턴스</p> </li> <li> <p>Stateless 설계는 수평 확장을 용이하게 합니다.</p> </li> <li> <p>필요한 경우 쿠버네티스를 오케스트레이션에 사용</p> </li> </ul> </div> <div class="paragraph"> <p><strong>PostgreSQL :</strong></p> </div> <div class="ulist"> <ul> <li> <p>대용량 테이블 파티셔닝</p> </li> <li> <p>연결 풀링 (PgBouncer)</p> </li> <li> <p>샤딩은 정말로 필요합니다 (희귀함)</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_건축적_증언">건축적 증언</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_스타트업_saas_50k_사용자">스타트업 SaaS (50k 사용자)</h3> <div class="paragraph"> <p><em><em>_ 우리는 Supabase로 100% 시작했습니다. 5k 사용자 수준에서 우리는 Stripe 결제 청구와 월간 보고서를 위해 Spring Boot만 추가했습니다. 1년 후, 우리의 운영 중 80%가 여전히 Supabase를 통해 이루어집니다. Spring Boot는 비판적인 부분만 처리합니다. 이러한 분리를 통해 리팩터링 없이 확장이 가능했습니다. </em>_</em></p> </div> </div> <div class="sect2"> <h3 id="_e_러닝_플랫폼_10k_사용자">E-러닝 플랫폼 (10k 사용자)</h3> <div class="paragraph"> <p><em><em>_ Supabase의 OAuth2 인증 덕분에 3주 개발 시간을 절약할 수 있었습니다. 자동 생성된 API가 전체 강의 카탈로그를 처리합니다. Spring Boot는 PDF 인증서와 진행 이메일에만 사용됩니다. 간단하고 유지보수 가능하며 확장 가능한 아키텍처. </think> </em><em></em></em><em><em></em><em></em></em><em><em></em><em></em></em><em><em></em>___</em></p> </div> </div> <div class="sect2"> <h3 id="_b2b_마켓플레이스_3k_사용자">B2B 마켓플레이스 (3k 사용자)</h3> <div class="paragraph"> <p><em><em>_ Spring Boot은 구매자와 판매자 간 거래를 관리합니다(중요). Supabase는 나머지 모든 것을 관리합니다: 프로필, 실시간 메시징, 문서. 그들이 동일한 PostgreSQL 데이터베이스를 공유한다는 사실 덕분에 복잡한 동기화를 피할 수 있습니다. 우리가 한 최고의 아키텍처 선택입니다. </em>_</em></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_요약_현대_건축_패러다임">요약 : 현대 건축 패러다임</h2> <div class="sectionbody"> <div class="paragraph"> <p>Supabase + Spring Boot 하이브리드 아키텍처는 새로운 패러다임을 나타냅니다 :<strong>건축 전문화</strong>.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE rectangle "구식 패러다임" #LightCoral { card "백엔드 안의 모든 것" { [Auth] [CRUD] [Logique Métier] [Jobs] [Storage] [Realtime] } note bottom Complexité maximale dès le jour 1 end note } rectangle "새로운 패러다임" #LightGreen { card "Supabase (편리함)" { [Auth] [CRUD Simple] [Storage] [Realtime] } card "Spring Boot (차별화)" { [Logique Métier] [Jobs] [Intégrations] } note bottom Complexité progressive ajoutée seulement si nécessaire end note } [Ancien Paradigme] -right-> [Nouveau Paradigme] : Évolution @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>기본 원칙 :</strong>이미 서비스 형태로 존재하는 것을 구축하지 마세요. 당신의 애플리케이션을 차별화하는 요소에 집중하세요.</p> </div> <div class="sect2"> <h3 id="_8020_법칙">80/20 법칙</h3> <div class="paragraph"> <p>대부분의 응용 프로그램에서:</p> </div> <div class="ulist"> <ul> <li> <p><strong>80%의 작업</strong>기본 CRUD → Supabase</p> </li> <li> <p><strong>20%의 운영</strong>비즈니스 로직이 필요 → Spring Boot</p> </li> </ul> </div> <div class="paragraph"> <p>이 자연스러운 규칙은 하이브리드 아키텍처를 정당화한다.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE package "운영 분배" { rectangle "80% - 표준 운영" #LightGreen { [Lecture de données] [Création d'entités] [Mise à jour simple] [Suppression] [Upload fichiers] [Authentification] note bottom: **Géré par Supabase** } rectangle "20% - 비즈니스 로직" #Coral { [Calculs complexes] [Workflows multi-étapes] [Transactions critiques] [Intégrations tierces] [Jobs planifiés] note bottom: **Géré par Spring Boot** } } note right **Focus optimal :** Votre temps de développement concentré sur les 20% qui différencient votre produit end note @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_최종_결론">최종 결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>하이브리드 아키텍처는 기술적인 타협이 아니라, 그것은<strong>전략적 결정</strong>.</p> </div> <div class="paragraph"> <p><strong>할 수 있습니다:</strong></p> </div> <div class="ulist"> <ul> <li> <p>✅ 기능적인 MVP로 빠르게 시작하기</p> </li> <li> <p>✅ 무거운 투자 없이 시장을 검증하세요</p> </li> <li> <p>복잡도가 요구될 때 점진적으로 발전시키다</p> </li> <li> <p>✅ 각 단계에서 비용을 관리하세요</p> </li> <li> <p>✅ 각 기술의 최고를 활용하다</p> </li> <li> <p>✅ 조기 과도한 엔지니어링 피하기</p> </li> <li> <p>✅ 미래를 위한 유연성 유지</p> </li> </ul> </div> <div class="paragraph"> <p><strong>그녀는 나타냅니다:</strong></p> </div> <div class="ulist"> <ul> <li> <p>🎯<strong>실용주의</strong>: 각 기술에서 그녀가 뛰어납니다</p> </li> <li> <p>🚀<strong>속도</strong>: Time-to-market 최소한의</p> </li> <li> <p>💰<strong>경제</strong>: 가치에 맞춘 비용</p> </li> <li> <p>🔮<strong>확장성</strong>함께 성장하는 아키텍처</p> </li> <li> <p>🛡️<strong>견고성</strong>: 검증되고 신뢰할 수 있는 서비스</p> </li> </ul> </div> <div class="sect2"> <h3 id="_당신의_다음_단계">당신의 다음 단계</h3> <div class="paragraph"> <p>이 아키텍처가 당신에게 와닿는다면, 여기서 시작하는 방법을 알려드릴게요:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Supabase 계정을 만드세요</strong>(무료)</p> </li> <li> <p><strong>최소한의 데이터 스키마를 정의하세요</strong></p> </li> <li> <p><strong>OAuth2 인증을 구성하세요</strong></p> </li> <li> <p><strong>당신의 첫 번째 JBake 페이지를 API를 소비하도록 생성하세요</strong></p> </li> <li> <p><strong>GitHub Pages에 배포하세요.</strong></p> </li> </ol> </div> <div class="paragraph"> <p>작동 가능한 MVP를 갖게 될 것입니다<strong>몇 일</strong>.</p> </div> <div class="paragraph"> <p>Spring Boot은 필요할 때 자연스럽게 따라올 것입니다. 그 이전에는 아닙니다.</p> </div> <hr> <div class="paragraph"> <p><strong>하이브리드 아키텍처는 필요한 것을 필요한 때에 정확히 만드는 예술이다.</strong></p> </div> <div class="paragraph"> <p><em>좋은 개발! 🚀</em></p> </div> <hr> <div class="paragraph"> <p>다른 개발자들이 올바른 아키텍처 선택을 할 수 있도록 도움이 될 것 같다면 이 글을 공유해 주세요.</p> </div> </div> </div> </div> https://cheroliv.com/blog/2026/0100_jbake_supabase_springboot_hybride_post.html Wed, 14 Jan 2026 00:00:00 +0000 blog/2026/0100_jbake_supabase_springboot_hybride_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">읽기 시간 : 12 minutes</div> <p>Supabase의 단순함과 Spring Boot의 강력함 사이에서 선택하는 대신, 왜 두 가지를 결합하지 않을까요? 각 기술의 장점을 활용하는 하이브리드 아키텍처를 살펴보세요.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">똑</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_현대_건축의_거짓_딜레마">현대 건축의 거짓 딜레마</h2> <div class="sectionbody"> <div class="paragraph"> <p>정적 프론트엔드를 사용해 현대적인 애플리케이션을 구축할 때, 종종 이진 선택에 직면하게 됩니다:</p> </div> <div class="ulist"> <ul> <li> <p><strong>백엔드-아즈-어-서비스 솔루션에 모든 것을 걸다</strong>(Supabase, Firebase) - 간단하지만 제한적인</p> </li> <li> <p><strong>완전한 백엔드 구축</strong>(Spring Boot, Node.js) - 강력하지만 복잡한</p> </li> </ul> </div> <div class="paragraph"> <p>이 선택은 허위의 딜레마다. 하이브리드 아키텍처는 세 번째 방법을 제시한다: <strong>각 기술이 뛰어난 곳에서 그 기술을 사용하라</strong></p> </div> </div> </div> <div class="sect1"> <h2 id="_건축적_비전">건축적 비전</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_전통적인_아키텍처_모놀리식">전통적인 아키텍처: 모놀리식</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "전통 건축" { actor Utilisateur as user component "프론트엔드" as frontend #LightBlue component "단일 백엔드" as backend #LightCoral { [Authentification] [CRUD] [Logique Métier] [Jobs] [APIs Tierces] } database "데이터베이스" as db #LightGray user --> frontend frontend --> backend : Toutes les requêtes backend --> db } note right of backend Tout passe par le backend même les opérations simples ⚠️ Point de congestion unique ⚠️ Complexité dès le départ ⚠️ Couplage fort end note @enduml</pre> </div> </div> <div class="paragraph"> <p>이 접근 방식에서는 가장 단순한 작업(게시글 읽기, 댓글 작성)도 백엔드를 거쳐야 합니다. 첫날부터 복잡성의 비용을 지불하게 됩니다.</p> </div> </div> <div class="sect2"> <h3 id="_baas_아키텍처_모든_대표">BaaS 아키텍처: 모든 대표</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "순수 BaaS 아키텍처" { actor Utilisateur as user component "프론트엔드" as frontend #LightBlue cloud "Supabase / Firebase" as baas #LightGreen { [Auth] [Database] [Storage] [Edge Functions] } user --> frontend frontend --> baas : Toutes les opérations } note right of baas Développement rapide Pas de serveur à gérer ⚠️ Limité pour logique complexe ⚠️ Vendor lock-in ⚠️ Edge Functions contraintes end note @enduml</pre> </div> </div> <div class="paragraph"> <p>반면에, BaaS에 모든 것을 위임하는 것은 처음에는 매력적이지만, 비즈니스 로직이 복잡해지면 바로 그 한계를 드러냅니다.</p> </div> </div> <div class="sect2"> <h3 id="_하이브리드_아키텍처_책임_분리">하이브리드 아키텍처: 책임 분리</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle actor Utilisateur as user #LightBlue package "프론트엔드 레이어" { component "정적 사이트 JBake" as frontend #SkyBlue } package "단순한 레이어 (Supabase)" #LightGreen { component "인증" as auth component "기본 CRUD" as crud component "파일 저장" as storage component "실시간" as realtime } package "비즈니스 레이어(Spring Boot)" #Coral { component "복잡한 논리" as logic component "오케스트레이션" as orchestration component "예정된 작업" as jobs component "통합" as integrations } database "공유 PostgreSQL" as db #LightGray user --> frontend frontend --> auth : OAuth2, JWT frontend --> crud : Articles, Profils frontend --> storage : Images, Fichiers frontend --> realtime : Notifications frontend --> logic : Calculs, Rapports frontend --> orchestration : Workflows logic --> integrations : Stripe, APIs orchestration --> db jobs --> db crud --> db auth --> db note bottom of db **Une seule source de vérité** Partagée entre Supabase et Spring Boot end note note right of auth **Gratuit jusqu'à 50k users** Configuration en quelques clics OAuth2 multi-providers end note note right of logic **Activé seulement si nécessaire** Kotlin + Coroutines Transactions complexes end note @enduml</pre> </div> </div> <div class="paragraph"> <p>하이브리드 아키텍처는 복잡성과 운영의 성격에 따라 책임을 명확히 구분한다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_디자인_원칙">디자인 원칙</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_원칙_1_간단하게_시작하고_지혜롭게_발전시키기">원칙 1: 간단하게 시작하고, 지혜롭게 발전시키기</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE rectangle "1단계: MVP" #LightGreen { component "JBake + Supabase" as mvp note right ✓ Développement en jours ✓ Coût : 0€ ✓ Validation concept end note } rectangle "**단계 2 : 성장**" #LightYellow { component "JBake + Supabase + Spring Boot (선택 사항)" as growth note right ✓ Logique métier émerge ✓ Premiers jobs planifiés ✓ Intégrations tierces end note } rectangle "**단계 3 : 확장**" #LightCoral { component "완전한 아키텍처" as scale note right ✓ Orchestration complexe ✓ Performances optimisées ✓ Cache distribué end note } mvp -down-> growth : Quand la complexité\nle justifie growth -down-> scale : Optimisation\ncontinue @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>필요하지 않다면 Spring Boot을 만들지 마세요.</strong>Supabase로 시작하고, 복잡성이 이를 정당화할 때 Spring Boot을 추가하세요.</p> </div> </div> <div class="sect2"> <h3 id="_원칙_2_운영의_성질에_따른_분리">원칙 2: 운영의 성질에 따른 분리</h3> <div class="listingblock"> <div class="content"> <pre>@startmindmap skinparam backgroundColor #FEFEFE * Opérations\nApplicatives left side ** Opérations Simples\n(Supabase) ***_ CRUD Standard ****_ Lecture ****_ Création ****_ Mise à jour ****_ Suppression ***_ Authentification ****_ Login/Logout ****_ OAuth2 ****_ Gestion session ***_ Stockage ****_ Upload fichiers ****_ CDN automatique ***_ Temps Réel ****_ WebSocket ****_ Notifications right side ** Opérations Complexes\n(Spring Boot) ***_ Logique Métier ****_ Calculs complexes ****_ Règles métier ****_ Validations avancées ***_ Orchestration ****_ Multi-services ****_ Transactions distribuées ****_ Saga patterns ***_ Tâches Planifiées ****_ Rapports périodiques ****_ Synchronisations ****_ Nettoyages ***_ Intégrations ****_ Paiements (Stripe) ****_ APIs tierces ****_ Services ML/AI @endmindmap</pre> </div> </div> </div> <div class="sect2"> <h3 id="_원칙_3_하나의_진실한_출처">원칙 3: 하나의 진실한 출처</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE database "PostgreSQL" as db #LightGray { package "스키마: auth (Supabase)" #LightGreen { [users] [sessions] [identities] } package "스키마: 공개 (공유)" #SkyBlue { [articles] [comments] [profiles] } package "스키마: 비즈니스 (스프링 부트)" #Coral { [orders] [payments] [reports] } } component "수퍼베이스" as supabase #LightGreen component "스프링 부트" as spring #Coral supabase -down-> users : Gère supabase -down-> sessions : Gère supabase -down-> articles : Accède supabase -down-> comments : Accède supabase -down-> profiles : Accède spring -down-> articles : Accède spring -down-> profiles : Accède spring -down-> orders : Gère spring -down-> payments : Gère spring -down-> reports : Gère note right of db **Avantages :** • Pas de synchronisation complexe • JOINs possibles entre tables • Cohérence garantie • Migrations unifiées end note @enduml</pre> </div> </div> <div class="paragraph"> <p>같은 PostgreSQL 인스턴스를 공유함으로써 Supabase와 Spring Boot는 복잡한 동기화 없이 동일한 데이터에서 작업합니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_플로우_오케스트레이션">플로우 오케스트레이션</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_플럭스_1_중앙_집중식_인증">플럭스 1: 중앙 집중식 인증</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE autonumber actor "사용자" as user participant "JBake" as jbake participant "Supabase 인증" as auth participant "스프링 부트" as spring database "PostgreSQL" as db == Authentification == user -> jbake : Clique "로그인" jbake -> auth : Redirect OAuth2 (Google/GitHub) auth -> user : Consent screen user -> auth : Autorise auth -> auth : Génère JWT auth -> jbake : Retourne JWT + Refresh Token jbake -> jbake : Stocke tokens (sessionStorage) == Accès aux Ressources == group Opération Simple (CRUD) user -> jbake : Crée un article jbake -> db : POST avec JWT note right: Supabase Row Level Security\nvérifie le JWT automatiquement db -> jbake : Article créé end group Opération Complexe (Métier) user -> jbake : Génère un rapport jbake -> spring : POST /api/reports\navec JWT spring -> spring : Valide JWT Supabase spring -> spring : Extrait claims (user_id, roles) spring -> db : Requêtes complexes spring -> jbake : Rapport généré end note over auth, spring **Le JWT est universel** Valide par Supabase ET Spring Boot Pas de double authentification end note @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>핵심 포인트</strong>하나의 인증 프로세스, 하나의 JWT, 어디서든 사용 가능</p> </div> </div> <div class="sect2"> <h3 id="_flux_2_복잡한_비즈니스_프로세스의_오케스트레이션">Flux 2: 복잡한 비즈니스 프로세스의 오케스트레이션</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE autonumber actor "클라이언트" as user participant "제이베이크" as jbake participant "스프링 부트" as spring participant "Supabase 데이터베이스" as supadb participant "스트라이프 API" as stripe participant "인벤토리 서비스" as inventory participant "이메일 서비스" as email database "포스트그레스큐엘" as db user -> jbake : Passe commande jbake -> spring : POST /api/orders/create == Orchestration Spring Boot == spring -> db : BEGIN TRANSACTION par Vérifications Parallèles spring -> inventory : Vérifier stock inventory -> spring : Stock OK else spring -> db : Vérifier profil client db -> spring : Client vérifié end spring -> stripe : Créer Payment Intent stripe -> spring : Intent créé (ID: pi_xxx) spring -> db : Créer Order (status: PENDING) db -> spring : Order créé spring -> stripe : Confirmer paiement stripe -> spring : Paiement confirmé spring -> db : Update Order (status: PAID) spring -> inventory : Décrémenter stock spring -> db : COMMIT TRANSACTION par Notifications Asynchrones spring -> email : Email confirmation else spring -> supadb : Insert notification note right: Notification temps réel\nvia Supabase Realtime end spring -> jbake : Order confirmé jbake -> user : Affiche confirmation note over spring **Responsabilités Spring Boot :** • Transaction ACID • Orchestration multi-services • Rollback automatique si erreur • Gestion des cas limites end note @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>Spring Boot가 제공하는 것</strong>: 신뢰성 있는 복잡한 프로세스를 여러 시스템에 걸쳐 구현하면서 트랜잭션 보증을 제공하는 오케스트레이션.</p> </div> </div> <div class="sect2"> <h3 id="_플럭스_3_예정된_작업_및_동기화">플럭스 3: 예정된 작업 및 동기화</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE participant "스케줄러 (스프링 부트)" as scheduler participant "리포트 서비스" as report participant "포스트그레스큐엘" as db participant "외부 API" as api participant "이메일 서비스" as email participant "Supabase 저장소" as storage == Job Quotidien : 2h00 == activate scheduler scheduler -> report : Déclenche génération rapport activate report report -> db : Récupère données\ndes dernières 24h db -> report : Dataset report -> report : Calculs & Agrégations report -> report : Génération PDF report -> storage : Upload PDF storage -> report : URL publique report -> email : Envoie aux admins\navec lien PDF deactivate report == Job Hebdomadaire : Dimanche 3h00 == scheduler -> report : Synchronisation externe activate report report -> api : Fetch données externes api -> report : Nouvelles données report -> db : Mise à jour tables report -> db : Nettoyage données obsolètes deactivate report == Job Mensuel : 1er du mois == scheduler -> report : Facturation activate report report -> db : Liste clients actifs report -> report : Calcul montants report -> api : Génération factures (Stripe) report -> email : Envoi factures deactivate report deactivate scheduler note right of scheduler **Impossible avec Supabase seul** Edge Functions non adaptées pour jobs longs et récurrents end note @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>Spring Boot가 제공하는 것</strong>: 신뢰할 수 있는 예약된 작업, 상태 관리, 자동 재시도, 그리고 보장된 실행.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_의사결정_매트릭스">의사결정 매트릭스</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_supabase를_언제_사용해야_하나요">Supabase를 언제 사용해야 하나요?</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE start :Nouvelle fonctionnalité à implémenter; if (CRUD simple ?) then (oui) :✅ **Supabase**; stop else (non) if (Authentification ?) then (oui) :✅ **Supabase Auth**; stop else (non) if (Upload fichiers ?) then (oui) :✅ **Supabase Storage**; stop else (non) if (Temps réel ?) then (oui) :✅ **Supabase Realtime**; stop else (non) if (Row Level Security\nsuffisante ?) then (oui) :✅ **Supabase + Policies**; stop else (non) :⚠️ **Considérer Spring Boot**; #Coral:Passer à l'arbre\nde décision Spring Boot; stop endif endif endif endif endif @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_spring_boot을_언제_사용해야_하나">Spring Boot을 언제 사용해야 하나?</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE start :Nouvelle fonctionnalité complexe; if (Orchestration\nmulti-services ?) then (oui) :✅ **Spring Boot**; stop else (non) if (Transaction ACID\ncritique ?) then (oui) :✅ **Spring Boot**; stop else (non) if (Job planifié ?) then (oui) :✅ **Spring Boot Scheduler**; stop else (non) if (Intégration API\ntierce complexe ?) then (oui) :✅ **Spring Boot**; stop else (non) if (Calculs lourds\n> 10 secondes ?) then (oui) :✅ **Spring Boot**; stop else (non) if (Cache distribué\nnécessaire ?) then (oui) :✅ **Spring Boot + Redis**; stop else (non) :⚠️ **Probablement Supabase**; #LightGreen:Revenir à l'arbre\nde décision Supabase; stop endif endif endif endif endif endif @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_프로젝트_유형별_아키텍처_예시">프로젝트 유형별 아키텍처 예시</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_블로그_포트폴리오">블로그 / 포트폴리오</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "개인 블로그 - 95% Supabase" { component "JBake" as jbake #SkyBlue package "Supabase (무료)" #LightGreen { [Auth: OAuth2 Google] [Articles (CRUD)] [Commentaires] [Images (Storage)] [Notifications Realtime] } package "Spring Boot (선택적)" #LightCoral { [Newsletter Mensuelle] note bottom: Job planifié uniquement } database "PostgreSQL" as db jbake --> [Auth: OAuth2 Google] jbake --> [Articles (CRUD)] jbake --> [Commentaires] jbake --> [Images (Storage)] jbake --> [Notifications Realtime] [Articles (CRUD)] --> db [Commentaires] --> db [Newsletter Mensuelle] --> db } note bottom of "Spring Boot (선택적)" **Spring Boot pas obligatoire** Newsletter peut être gérée par un service tiers (Mailchimp) end note @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>판결</strong>: 100% Supabase면 충분합니다.</p> </div> </div> <div class="sect2"> <h3 id="_saas_애플리케이션">SaaS 애플리케이션</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "SaaS 애플리케이션 - 하이브리드 아키텍처" { component "JBake / React" as frontend #SkyBlue package "Supabase" #LightGreen { [Auth Multi-tenant] [Profils Utilisateurs] [Données Simples] [Storage Documents] } package "스프링 부트" #Coral { [Facturation (Stripe)] [Analytics Avancées] [Rapports Mensuels] [Quotas & Limites] [Webhooks Stripe] } cloud "외부 서비스" { [Stripe API] [SendGrid Email] } database "공유된 PostgreSQL" as db frontend --> [Auth Multi-tenant] frontend --> [Profils Utilisateurs] frontend --> [Données Simples] frontend --> [Facturation (Stripe)] frontend --> [Analytics Avancées] [Auth Multi-tenant] --> db [Profils Utilisateurs] --> db [Données Simples] --> db [Facturation (Stripe)] --> db [Facturation (Stripe)] --> [Stripe API] [Analytics Avancées] --> db [Rapports Mensuels] --> db [Rapports Mensuels] --> [SendGrid Email] [Webhooks Stripe] ..> [Stripe API] : Écoute } note right of "스프링 부트" **Nécessaire pour :** • Gestion abonnements • Facturation récurrente • Quotas dynamiques • Analytics complexes • Webhooks fiables end note @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>판결</strong>필요한 하이브리드 아키텍처. 핵심 부분은 Supabase를 사용하고, 중요한 부분(결제, 청구)에는 Spring Boot를 사용합니다.</p> </div> </div> <div class="sect2"> <h3 id="_이커머스">이커머스</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "E-커머스 - 70% Spring Boot" { component "매장 (JBake/React)" as frontend #SkyBlue package "Supabase" #LightGreen { [Auth Clients] [Catalogue Produits\n(lecture seule)] [Images Produits] } package "Spring Boot (핵심 비즈니스)" #Coral { [Gestion Commandes] [Paiements Stripe] [Gestion Stock] [Calcul Frais Port] [Génération Factures] [Synchronisation ERP] [Emails Transactionnels] } cloud "통합" { [Stripe] [Transporteur API] [ERP Externe] } database "PostgreSQL" as db frontend --> [Auth Clients] frontend --> [Catalogue Produits\n(lecture seule)] frontend --> [Gestion Commandes] [Auth Clients] --> db [Catalogue Produits\n(lecture seule)] --> db [Gestion Commandes] --> db [Paiements Stripe] --> [Stripe] [Gestion Stock] --> db [Calcul Frais Port] --> [Transporteur API] [Génération Factures] --> db [Synchronisation ERP] --> [ERP Externe] [Synchronisation ERP] --> db } note right of "Spring Boot (핵심 비즈니스)" **Spring Boot indispensable :** • Transactions critiques • Orchestration complexe • Intégrations multiples • Conformité légale • Jobs de synchronisation end note @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>판결</strong>: Spring Boot 필수적입니다. Supabase은 인증 및 카탈로그에만 사용.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_점진적_마이그레이션_전략">점진적 마이그레이션 전략</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE |Semaine 1-2| start :Créer projet Supabase; :Configurer Auth (Google, GitHub); :Définir schéma PostgreSQL initial; :Implémenter CRUD de base sur JBake; :Déployer MVP sur GitHub Pages; note right **Livrable :** Application fonctionnelle **Coût :** 0€ **Temps :** 1-2 semaines end note |Semaine 3-4| :Observer utilisation réelle; :Identifier limitations; |Décision| if (Logique complexe\némerge ?) then (non) |Supabase| :Continuer avec Supabase seul; :Ajouter Edge Functions si besoin; stop else (oui) |Spring Boot| :Créer projet Spring Boot; :Configurer validation JWT Supabase; :Migrer logique complexe vers Spring Boot; note right **Migration sélective** Seulement ce qui est complexe end note endif |Semaines suivantes| :Déployer Spring Boot (Cloud Run, EC2); :Connecter à PostgreSQL Supabase; :Implémenter premiers jobs planifiés; :Intégrer APIs tierces; stop note right **Architecture finale hybride** Supabase + Spring Boot en parfaite harmonie end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_비용_및_운영_고려_사항">비용 및 운영 고려 사항</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_비용_구조">비용 구조</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE package "예상 월간 비용" { rectangle "MVP 단계 (0-1000 사용자)" #LightGreen { [JBake (GitHub Pages): 0€] [Supabase: 0€] [Spring Boot: N/A] note bottom: **Total: 0€/mois** } rectangle "성장 단계 (1k-10k 사용자)" #LightYellow { [JBake (GitHub Pages): 0€] [Supabase: 0€] [Spring Boot (Cloud Run): 20-50€] [PostgreSQL (si séparé): 0-30€] note bottom: **Total: 20-80€/mois** } rectangle "단계 규모\n(10k-100k 사용자)" #LightCoral { [JBake (Netlify Pro): 19€] [Supabase Pro: 25€] [Spring Boot (instances multiples): 100-300€] [Redis Cache: 20-50€] [Monitoring: 20€] note bottom: **Total: 184-414€/mois** } } note right of "단계 규모\n(10k-100k 사용자)" À ce stade, les revenus justifient largement les coûts end note @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_운영_책임">운영 책임</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE package "누가 무엇을 관리하나요?" { rectangle "Supabase에서 관리 (0 노력)" #LightGreen { [Authentification] [Base de données] [Backups automatiques] [Scaling automatique] [Monitoring DB] [Sécurité DB] } rectangle "GitHub에 의해 관리됨 (노력 0)" #SkyBlue { [Hébergement site statique] [HTTPS/SSL] [CDN global] [Déploiement automatique] } rectangle "관리해야 할 (Spring Boot)" #LightCoral { [Déploiement application] [Monitoring APM] [Logs centralisés] [Scaling horizontal] [Mises à jour sécurité] } } note bottom of "관리해야 할 (Spring Boot)" **Minimisable avec :** • Cloud Run (serverless) • Kubernetes (si nécessaire) • Services managés (RDS, etc.) end note @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_결론_완벽한_균형">결론: 완벽한 균형</h2> <div class="sectionbody"> <div class="paragraph"> <p>Supabase + Spring Boot 하이브리드 아키텍처는 타협이 아니며, 그것은<strong>시너지</strong>.</p> </div> <div class="sect2"> <h3 id="_기억해야_할_원칙들">기억해야 할 원칙들</h3> <div class="listingblock"> <div class="content"> <pre>@startmindmap skinparam backgroundColor #FEFEFE * Architecture\nHybride ** Commencer Simple ***_ MVP avec Supabase ***_ 0€ de coût initial ***_ Validation rapide ** Évoluer Intelligemment ***_ Ajouter Spring Boot\nsi nécessaire ***_ Migration progressive ***_ Pas de refonte totale ** Exploiter les Forces ***_ Supabase: Simplicité ***_ Spring Boot: Puissance ***_ PostgreSQL: Source unique ** Minimiser la Complexité ***_ Pas de synchronisation ***_ Pas de duplication ***_ Architecture claire ** Optimiser les Coûts ***_ Gratuit au départ ***_ Scaling progressif ***_ ROI évident @endmindmap</pre> </div> </div> </div> <div class="sect2"> <h3 id="_이_아키텍처를_언제_선택해야_할까요">이 아키텍처를 언제 선택해야 할까요?</h3> <div class="paragraph"> <p><strong>✅ 이 아키텍처는 다음과 같은 경우에 이상적입니다 :</strong></p> </div> <div class="ulist"> <ul> <li> <p>당신은 빠르게 시작하고 싶습니다 (MVP는 개월이 아닌 일 단위입니다)</p> </li> <li> <p>당신은 비즈니스 복잡성 성장을 예상합니다.</p> </li> <li> <p>초기 비용을 최소화하고 싶습니다.</p> </li> <li> <p>PostgreSQL을 좋아하고 단일 진실의 원천을 원합니다.</p> </li> <li> <p>당신은 비즈니스 로직을 위해 Kotlin과 코루틴을 좋아합니다.</p> </li> <li> <p>전체적인 벤더 락인을 피하고 싶으세요?</p> </li> </ul> </div> <div class="paragraph"> <p><strong>❌ 다음 조건이면 이 아키텍처는 적합하지 않습니다:</strong></p> </div> <div class="ulist"> <ul> <li> <p>귀하의 프로젝트는 간단하며 그대로 유지됩니다 (개인 블로그 → 100% Supabase이면 충분합니다)</p> </li> <li> <p>당신은 이미 확립된 백엔드 스택을 숙지하고 있습니다.</p> </li> <li> <p>당신은 전통적인 모놀리스를 선호합니다</p> </li> <li> <p>.NET, Python, 또는 다른 백엔드 언어가 필요합니다.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_최종_전체_비전">최종 전체 비전</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE package "완전한 하이브리드 아키텍처" { actor "사용자" as users rectangle "프론트엔드 (정적)" #SkyBlue { [JBake / GitHub Pages] note right: Gratuit, CDN global } rectangle "간단한 백엔드 (Supabase)" #LightGreen { [Auth OAuth2] [CRUD APIs] [Storage] [Realtime] note right Gratuit jusqu'à 50k users Zéro configuration serveur end note } rectangle "비즈니스 백엔드 (Spring Boot)" #Coral { [Orchestration] [Jobs Planifiés] [Intégrations] [Transactions] note right Activé uniquement si nécessaire end note } database "PostgreSQL 단일 진실의 원천" as db #LightGray users --> [JBake / GitHub Pages] [JBake / GitHub Pages] --> [Auth OAuth2] [JBake / GitHub Pages] --> [CRUD APIs] [JBake / GitHub Pages] --> [Storage] [JBake / GitHub Pages] --> [Realtime] [JBake / GitHub Pages] --> [Orchestration] [Auth OAuth2] --> db [CRUD APIs] --> db [Orchestration] --> db [Jobs Planifiés] --> db [Intégrations] --> db } note bottom of db **Une seule base, deux consommateurs** • Supabase pour le simple • Spring Boot pour le complexe • Aucune synchronisation requise end note @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_두_세계의_최고">두 세계의 최고</h3> <div class="paragraph"> <p>이 아키텍처는 당신에게 제공합니다:</p> </div> <div class="paragraph"> <p><strong>🚀 서프베이스의 속도</strong></p> </div> <div class="ulist"> <ul> <li> <p>시간 단위로 시작하는 것이지, 주 단위가 아닙니다.</p> </li> <li> <p>몇 번의 클릭으로 간편한 OAuth2 인증</p> </li> <li> <p>자동으로 생성된 REST API</p> </li> <li> <p>서버 무설정</p> </li> </ul> </div> <div class="paragraph"> <p><strong>💪 Spring Boot의 힘</strong></p> </div> <div class="ulist"> <ul> <li> <p>코틀린과 코루틴을 이용한 우아한 비동기 코드</p> </li> <li> <p>복잡한 업무 프로세스 오케스트레이션</p> </li> <li> <p>신뢰할 수 있는 예약된 작업</p> </li> <li> <p>ACID 트랜잭션 보장</p> </li> <li> <p>완전한 스프링 생태계</p> </li> </ul> </div> <div class="paragraph"> <p><strong>💰 진보적인 경제</strong></p> </div> <div class="ulist"> <ul> <li> <p>0€로 시작하고 확인하기</p> </li> <li> <p>성장과 함께 증가하는 비용</p> </li> <li> <p>조기 과도한 엔지니어링 금지</p> </li> </ul> </div> <div class="paragraph"> <p><strong>🎯 건축적 유연성</strong></p> </div> <div class="ulist"> <ul> <li> <p>재구축 없이 점진적인 마이그레이션</p> </li> <li> <p>필요한 경우에만 Spring Boot 추가</p> </li> <li> <p>전체적인 벤더 락인이 없습니다.</p> </li> <li> <p>진화형 아키텍처</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_더_깊이_가기_위해">더 깊이 가기 위해</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_기술_자원">기술 자원</h3> <div class="paragraph"> <p><strong>Supabase 문서 :</strong></p> </div> <div class="ulist"> <ul> <li> <p><a href="https://supabase.com/docs/guides/auth">인증 가이드</a></p> </li> <li> <p><a href="https://supabase.com/docs/guides/database/postgres/row-level-security">행 수준 보안</a></p> </li> <li> <p><a href="https://supabase.com/docs/guides/api">자동 생성된 API</a></p> </li> </ul> </div> <div class="paragraph"> <p><strong>스프링 부트 문서 :</strong></p> </div> <div class="ulist"> <ul> <li> <p><a href="https://spring.io/guides/tutorials/spring-boot-kotlin/">Kotlin과 함께 Spring Boot</a></p> </li> <li> <p><a href="https://spring.io/blog/2019/04/12/going-reactive-with-spring-coroutines-and-kotlin-flow">코루틴과 스프링</a></p> </li> <li> <p><a href="https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html">JWT 리소스 서버</a></p> </li> </ul> </div> <div class="paragraph"> <p><strong>추가 조항 :</strong></p> </div> <div class="ulist"> <ul> <li> <p>JWT를 사용한 API 보안</p> </li> <li> <p>PostgreSQL 성능 최적화</p> </li> <li> <p>점진적 마이그레이션 패턴</p> </li> <li> <p>분산 아키텍처에서 오류 관리</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_실제_사용_사례">실제 사용 사례</h3> <div class="paragraph"> <p>이 하이브리드 아키텍처는 다음과 같이 성공적으로 사용됩니다 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>SaaS B2B</strong>: Supabase 인증, Spring Boot 청구</p> </li> <li> <p><strong>마켓플레이스</strong>: 카탈로그 Supabase, 트랜잭션 Spring Boot</p> </li> <li> <p><strong>콘텐츠 플랫폼</strong>Supabase 글, Spring Boot 분석</p> </li> <li> <p><strong>내부 도구</strong>CRUD Supabase, Spring Boot 워크플로우</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_시작_체크리스트">시작 체크리스트</h3> <div class="paragraph"> <p><strong>Phase 1 - 기초 (1주)</strong></p> </div> <div class="ulist checklist"> <ul class="checklist"> <li> <p><i class="fa fa-square-o"></i> Supabase 계정 만들기 - [ ] PostgreSQL 프로젝트 구성하기 - [ ] 인증 활성화 (Google, GitHub) - [ ] 초기 스키마 정의 - [ ] Row Level Security 설정 - [ ] JBake에서 API 테스트</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Phase 2 - MVP (2-3주)</strong></p> </div> <div class="ulist checklist"> <ul class="checklist"> <li> <p><i class="fa fa-square-o"></i> 주요 페이지 구현 - [ ] OAuth2 인증 통합 - [ ] CRUD 폼 생성 - [ ] 파일용 Storage 설정 - [ ] GitHub Pages에 배포 - [ ] 실제 조건에서 테스트하기</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Phase 3 - 진화 (필요에 따라)</strong></p> </div> <div class="ulist checklist"> <ul class="checklist"> <li> <p><i class="fa fa-square-o"></i> 복잡한 논리 필요 사항 식별 - [ ] 필요 시 Spring Boot 프로젝트 생성 - [ ] Supabase JWT 검증 구성 - [ ] Supabase PostgreSQL에 연결하기 - [ ] 복잡한 기능 마이그레이션 - [ ] 예약된 작업 구현 - [ ] Spring Boot 배포하기 (Cloud Run 등)</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_피해야_할_반패턴">피해야 할 반패턴</h3> <div class="paragraph"> <p><strong>❌ 하지 말아야 할 것 :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Supabase와 Spring Boot 사이에 데이터를 복제</p> </li> <li> <p>두 개의 별도 PostgreSQL 데이터베이스를 생성</p> </li> <li> <p>인증 직접 코딩하기</p> </li> <li> <p>Spring Boot를 사용하여 간단한 CRUD를 구현하다</p> </li> <li> <p>처음부터 과도하게 설계하다</p> </li> <li> <p>Supabase의 Row Level Security 무시하기</p> </li> </ul> </div> <div class="paragraph"> <p><strong>✅ 더 나은 행동 :</strong></p> </div> <div class="ulist"> <ul> <li> <p>하나의 PostgreSQL 데이터베이스 공유</p> </li> <li> <p>Supabase가 인증을 관리하도록 두다</p> </li> <li> <p>복잡성을 위해 Spring Boot만 사용</p> </li> <li> <p>간단히 시작하고, 점차적으로 발전시키다</p> </li> <li> <p>각 기술의 강점을 활용</p> </li> <li> <p>데이터베이스 수준에서 RLS를 적용하여 보안하기</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_진화_전망">진화 전망</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_새로운_기능_추가">새로운 기능 추가</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE rectangle "현재 아키텍처" #SkyBlue { [JBake] [Supabase] [Spring Boot] } rectangle "가능한 발전" #LightYellow { package "성능" { [Redis Cache] [CDN pour Assets] [PostgreSQL Replicas] } package "모니터링" { [Grafana] [Prometheus] [Sentry] } package "지속적 통합/지속적 배포" { [GitHub Actions] [Tests Automatisés] [Déploiement Continu] } package "기능" { [Search (ElasticSearch)] [Queue (RabbitMQ)] [Event Sourcing] } } [Spring Boot] .down.> [Redis Cache] : Peut ajouter [Spring Boot] .down.> [Queue (RabbitMQ)] : Peut ajouter [Spring Boot] .down.> [Search (ElasticSearch)] : Peut ajouter [Supabase] .down.> [PostgreSQL Replicas] : Peut ajouter note bottom **Architecture extensible** Chaque ajout est indépendant Pas de refonte globale nécessaire end note @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_수평_스케일링">수평 스케일링</h3> <div class="paragraph"> <p>애플리케이션이 성장함에 따라 하이브리드 아키텍처는 자연스럽게 확장됩니다:</p> </div> <div class="paragraph"> <p><strong>Supabase :</strong></p> </div> <div class="ulist"> <ul> <li> <p>자동으로 수백만 건의 작업까지 확장</p> </li> <li> <p>읽기 전용 복제본을 위한 읽기 성능</p> </li> <li> <p>안전을 위한 시점 복구</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Spring Boot:</strong></p> </div> <div class="ulist"> <ul> <li> <p>로드 밸런서 뒤에 여러 인스턴스</p> </li> <li> <p>무상태 설계는 수평 스케일링을 용이하게 한다.</p> </li> <li> <p>필요에 따라 오케스트레이션을 위한 Kubernetes</p> </li> </ul> </div> <div class="paragraph"> <p><strong>PostgreSQL :</strong></p> </div> <div class="ulist"> <ul> <li> <p>대용량 테이블 파티셔닝</p> </li> <li> <p>연결 풀링 (PgBouncer)</p> </li> <li> <p>샤딩이 정말로 필요할 때(드물게)</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_건축학적_증언">건축학적 증언</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_startup_saas_50k_사용자">Startup SaaS (50k 사용자)</h3> <div class="paragraph"> <p><em><em>_ 우리는 100% Supabase로 시작했습니다. 5k 사용자 때, 우리는 Stripe 결제 처리와 월간 보고서를 위해서만 Spring Boot를 추가했습니다. 1년 후, 우리 운영의 80%는 여전히 Supabase를 통해 처리됩니다. Spring Boot는 오직 핵심 부분만 처리합니다. 이 분리 덕분에 우리는 재설계 없이 확장할 수 있었습니다. </em>_</em></p> </div> </div> <div class="sect2"> <h3 id="_e_러닝_플랫폼_10k_사용자">E-러닝 플랫폼 (10k 사용자)</h3> <div class="paragraph"> <p><em><em>_ Supabase의 OAuth2 인증은 3주 개발 시간을 절약해 주었습니다. 자동 생성된 API는 우리 강의 카탈로그 전체를 처리합니다. Spring Boot는 PDF 인증서와 진행 상황 이메일에만 사용됩니다. 간단하고 유지보수 가능하며 확장 가능한 아키텍처. </em>_</em></p> </div> </div> <div class="sect2"> <h3 id="_b2b_마켓플레이스_3k_사용자">B2B 마켓플레이스 (3k 사용자)</h3> <div class="paragraph"> <p><em><em>_ Spring Boot은 구매자와 판매자 간의 거래를 처리합니다(중요). Supabase는 나머지 모든 것을 처리합니다: 프로필, 실시간 메시징, 문서. 그들이 동일한 PostgreSQL 데이터베이스를 공유한다는 사실은 복잡한 동기화를 피하게 해줍니다. 우리가 내린 최고의 아키텍처 선택입니다. </em>_</em></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_요약_현대적인_건축_패러다임">요약: 현대적인 건축 패러다임</h2> <div class="sectionbody"> <div class="paragraph"> <p>Supabase + Spring Boot 하이브리드 아키텍처는 새로운 패러다임을 나타냅니다 :<strong>건축 전문 분야</strong>.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE rectangle "구식 패러다임" #LightCoral { card "백엔드 안의 모든 것" { [Auth] [CRUD] [Logique Métier] [Jobs] [Storage] [Realtime] } note bottom Complexité maximale dès le jour 1 end note } rectangle "새로운 패러다임" #LightGreen { card "Supabase (편의)" { [Auth] [CRUD Simple] [Storage] [Realtime] } card "Spring Boot (차별화)" { [Logique Métier] [Jobs] [Intégrations] } note bottom Complexité progressive ajoutée seulement si nécessaire end note } [Ancien Paradigme] -right-> [Nouveau Paradigme] : Évolution @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>기본적인 원칙 :</strong>이미 서비스로 존재하는 것을 만들지 마세요. 당신의 애플리케이션을 차별화하는 것에 집중하세요.</p> </div> <div class="sect2"> <h3 id="_8020_법칙">80/20 법칙</h3> <div class="paragraph"> <p>대부분의 응용 프로그램에서:</p> </div> <div class="ulist"> <ul> <li> <p><strong>80%의 운영</strong>표준 CRUD → Supabase</p> </li> <li> <p><strong>20%의 운영</strong>비즈니스 로직이 필요함 → Spring Boot</p> </li> </ul> </div> <div class="paragraph"> <p>이 자연스러운 규칙은 하이브리드 아키텍처를 정당화합니다.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam backgroundColor #FEFEFE package "작업 분배" { rectangle "80% - 표준 운영" #LightGreen { [Lecture de données] [Création d'entités] [Mise à jour simple] [Suppression] [Upload fichiers] [Authentification] note bottom: **Géré par Supabase** } rectangle "20% - 비즈니스 로직" #Coral { [Calculs complexes] [Workflows multi-étapes] [Transactions critiques] [Intégrations tierces] [Jobs planifiés] note bottom: **Géré par Spring Boot** } } note right **Focus optimal :** Votre temps de développement concentré sur les 20% qui différencient votre produit end note @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_최종_결론">최종 결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>하이브리드 아키텍처는 기술적 타협이 아닙니다, 그것은<strong>전략적 결정</strong>.</p> </div> <div class="paragraph"> <p><strong>다음과 같이 할 수 있습니다:</strong></p> </div> <div class="ulist"> <ul> <li> <p>✅ 기능적인 MVP로 빠르게 시작하기</p> </li> <li> <p>✅ 큰 투자 없이 시장 검증</p> </li> <li> <p>✅ 복잡함이 요구될 때 점진적으로 발전하다</p> </li> <li> <p>✅ 각 단계에서 비용을 관리하세요</p> </li> <li> <p>✅ 각 기술의 장점 활용</p> </li> <li> <p>조기 과설계 방지</p> </li> <li> <p>✅ 미래를 위해 유연성을 유지</p> </li> </ul> </div> <div class="paragraph"> <p><strong>그녀는:</strong></p> </div> <div class="ulist"> <ul> <li> <p>🎯<strong>실용주의</strong>: 그녀의 뛰어난 모든 기술</p> </li> <li> <p>🚀<strong>속도</strong>: 최소한의 시장 출시 시간</p> </li> <li> <p>💰<strong>경제</strong>가치에 부합하는 비용</p> </li> <li> <p>🔮<strong>확장성</strong>당신과 함께 성장하는 아키텍처</p> </li> <li> <p>🛡️<strong>견고성</strong>: 검증된 신뢰할 수 있는 서비스</p> </li> </ul> </div> <div class="sect2"> <h3 id="_다음_단계">다음 단계</h3> <div class="paragraph"> <p>이 아키텍처가 당신에게 와닿는다면, 여기서 시작하는 방법을 알려드립니다:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Supabase 계정을 생성하세요</strong>(무료)</p> </li> <li> <p><strong>최소 데이터 스키마를 정의하세요</strong></p> </li> <li> <p><strong>OAuth2 인증을 구성하세요</strong></p> </li> <li> <p><strong>당신의 첫 JBake 페이지를 만들어 API를 소비하세요.</strong></p> </li> <li> <p><strong>GitHub Pages에 배포하세요</strong></p> </li> </ol> </div> <div class="paragraph"> <p>작동 가능한 MVP를 갖게 될<strong>며칠</strong>.</p> </div> <div class="paragraph"> <p>Spring Boot은 필요할 때 자연스럽게 올 것입니다. 그 이전에는 오지 않을 것입니다.</p> </div> <hr> <div class="paragraph"> <p><strong>하이브리드 아키텍처는 필요한 것을 필요한 때에 정확히 구축하는 예술이다.</strong></p> </div> <div class="paragraph"> <p>좋은 개발! 🚀_</p> </div> <hr> <div class="paragraph"> <p><em>"이 기사를 공유하면 다른 개발자들이 올바른 아키텍처 선택을 하는 데 도움이 될 거라고 생각한다면 공유해 주세요."</em></p> </div> </div> </div> </div> https://cheroliv.com/blog/2025/0098_preloading_css_variable_post.html Sat, 15 Nov 2025 00:00:00 +0000 blog/2025/0098_preloading_css_variable_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_요약">요약</a></li> <li><a href="#_문제_이_저주받은_테마_깜박임">문제: 이 저주받은 테마 깜박임</a> <ul class="sectlevel2"> <li><a href="#_사용자_경험의_악몽">사용자 경험의 악몽</a></li> <li><a href="#_fouc_오래된_웹_문제">FOUC: 오래된 웹 문제</a></li> <li><a href="#_품질_인식에_대한_영향">품질 인식에 대한 영향</a></li> <li><a href="#_문제의_기술적_분석">문제의 기술적 분석</a></li> </ul> </li> <li><a href="#_왜_클래식_스크립트가_충분하지_않을까요">왜 클래식 스크립트가 충분하지 않을까요?</a> <ul class="sectlevel2"> <li><a href="#_직관적이지만_비효율적인_접근">직관적이지만 비효율적인 접근</a></li> <li><a href="#_domcontentloaded_이벤트_이해">DOMContentLoaded 이벤트 이해</a></li> <li><a href="#_렌더_블로킹_문제">렌더 블로킹 문제</a></li> <li><a href="#_문제_시각화">문제 시각화</a></li> <li><a href="#_효과_없는_해결_시도들">효과 없는 해결 시도들</a></li> <li><a href="#_진정한_해결책_더_빨리_행동하기">진정한 해결책 : 더 빨리 행동하기</a></li> </ul> </li> <li><a href="#_해결책_사전_로딩_early_loading">해결책 : 사전 로딩 (Early Loading)</a> <ul class="sectlevel2"> <li><a href="#_기본_원칙">기본 원칙</a></li> <li><a href="#_왜_head가_이상적인_장소인가">왜 `<head>`가 이상적인 장소인가?</a></li> <li><a href="#_3층_솔루션_아키텍처">3층 솔루션 아키텍처</a></li> </ul> </li> <li><a href="#_단계_1_사용자_선택_저장">단계 1 : 사용자 선택 저장</a> <ul class="sectlevel2"> <li><a href="#_localstorage_당신의_지속적인_메모리">localStorage : 당신의 지속적인 메모리</a></li> <li><a href="#_테마_백업_구현">테마 백업 구현</a></li> <li><a href="#_오류_케이스_관리">오류 케이스 관리</a></li> <li><a href="#_고급_지속성_전략">고급 지속성 전략</a></li> </ul> </li> <li><a href="#_단계_2_head_내의_프리로드_스크립트">단계 2: <code><head></code> 내의 프리로드 스크립트</a> <ul class="sectlevel2"> <li><a href="#_해결책의_핵심">해결책의 핵심</a></li> <li><a href="#_스크립트_해부_모든_라인이_중요">스크립트 해부: 모든 라인이 중요</a></li> <li><a href="#_시스템_선호도_감지_보너스">시스템 선호도 감지 (보너스)</a></li> <li><a href="#_성능_왜_이_스크립트는_빠른가">성능 : 왜 이 스크립트는 빠른가</a></li> <li><a href="#_head_안에_최적의_배치"><head>` 안에 최적의 배치</a></li> </ul> </li> <li><a href="#_단계_3_css_속성_선택자의_힘">단계 3 : CSS 속성 선택자의 힘</a> <ul class="sectlevel2"> <li><a href="#_bootstrap_5_테마_시스템">Bootstrap 5 테마 시스템</a></li> <li><a href="#_테마_시스템을_위한_css_구조">테마 시스템을 위한 CSS 구조</a></li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_요약">요약</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 기술적인 심도 있는 글에서, 우리는 페이지 로드 중에 발생하는 불쾌한 깜박임 효과 없이 라이트/다크 테마 선택기를 구현하는 방법을 탐구합니다. 우리는 브라우저 렌더링 주기를, FOUC(플래시 언스타일드 콘텐츠)의 근본 원인을 파악한 후, 동기식 사전 로드를 기반으로 한 견고한 솔루션을 제안합니다. 안의`<head>`. 이 기술은 원활하고 전문적인 사용자 경험을 보장합니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_문제_이_저주받은_테마_깜박임">문제: 이 저주받은 테마 깜박임</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_사용자_경험의_악몽">사용자 경험의 악몽</h3> <div class="paragraph"> <p>상상을 해보세요: 웹 애플리케이션용 아름다운 다크 테마를 디자인하는 데 몇 시간을 보냈습니다. 색상이 완벽하게 균형을 이루고, 대비가 최적이며, 사용자들이 이 옵션을 좋아합니다. 하지만 부끄러운 문제가 있습니다: 페이지를 새로 고칠 때마다, 몇 분의 1초 동안 기본 라이트 테마가 표시된 후 다크 테마가 적용됩니다.</p> </div> <div class="paragraph"> <p>이 시각적 '플래시’는 짧을 때도 (가끔 100ms 미만이지만) 인간의 눈에는 즉시 느껴지며 불쾌한 경험을 만든다. 어두운 테마를 시각적 편안함이나 접근성을 위해 선택한 사용자에게는 이 깜박임이 심지어 고통스러울 수 있다. 특히 조명이 어두운 환경에서는 더욱 그렇다.</p> </div> </div> <div class="sect2"> <h3 id="_fouc_오래된_웹_문제">FOUC: 오래된 웹 문제</h3> <div class="paragraph"> <p>이 현상은 "Flash of Unstyled Content" (FOUC)라고 부르는 것의 변형이며, 이는 CSS 초기 시절부터 이어져 온 웹 개발의 고전적인 문제입니다. FOUC는 브라우저가 CSS 스타일이 적용되지 않은 HTML 콘텐츠를 일시적으로 표시할 때 발생하며, 이로 인해 스타일이 적용되지 않은 콘텐츠의 플래시가 발생합니다.</p> </div> <div class="paragraph"> <p>우리 특정 사례에서는 완전히 스타일이 적용되지 않은 콘텐츠에 대해 말하는 것이 아니라, 오히려<strong>잘못된 테마의 플래시</strong>(FOWT) - 내용이 스타일링되지만 잘못된 테마가 적용됩니다. 이는 특히 짜증나는 데, 애플리케이션이 페이지 로드마다 사용자 선호를 "잊어버린다"는 것을 보여주기 때문입니다.</p> </div> </div> <div class="sect2"> <h3 id="_품질_인식에_대한_영향">품질 인식에 대한 영향</h3> <div class="paragraph"> <p>이 문제는 기술적인 문제이지만, 귀하의 애플리케이션 품질에 대한 인상에 중대한 영향을 미칩니다 :</p> </div> <div class="paragraph"> <p><strong>마감 부족</strong>깜빡임은 애플리케이션이 완성되지 않았거나 최적화가 부족했다는 인상을 줍니다. 사용자들은 종종 이러한 작은 시각적 결함을 전반적인 전문성 부족과 연관시킵니다.</p> </div> <div class="paragraph"> <p><strong>일관성 붕괴</strong>: 응용 프로그램은 사용자의 선호를 "잊어버린" 것처럼 보이며, 이는 인터페이스와 기대 사이의 비동기화 감각을 만든다.</p> </div> <div class="paragraph"> <p><strong>눈 피로</strong>빛에 민감한 사용자나 편두통을 앓는 사용자에게는 이 밝은 플래시가 단순한 미적 불편함을 넘어설 수 있습니다.</p> </div> <div class="paragraph"> <p><strong>인식된 성능</strong>아이러니하게도, 사이트가 빠르게 로드되더라도 이 깜빡거림은 느리거나 반응이 느린 애플리케이션처럼 느껴질 수 있습니다.</p> </div> </div> <div class="sect2"> <h3 id="_문제의_기술적_분석">문제의 기술적 분석</h3> <div class="paragraph"> <p>이 문제를 해결하는 방법을 이해하려면 먼저 왜 발생하는지 이해해야 합니다. 깜박임은 웹 페이지 생명 주기의 세 가지 중요한 사건 사이의 시간적 차이로 인해 발생합니다.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>HTML의 초기 파싱</strong>브라우저는 페이지 구조를 읽고 분석합니다.</p> </li> <li> <p><strong>CSS 스타일의 적용</strong>: 브라우저가 CSS 규칙을 적용하고 시각적 렌더링을 계산</p> </li> <li> <p><strong>JavaScript 실행</strong>: 테마를 바꾸는 코드가 실행됩니다</p> </li> </ol> </div> <div class="paragraph"> <p>문제는 이벤트 3번(자바스크립트 실행)이 브라우저가 이미 시작했거나 이벤트 2번(스타일 적용)을 마친 후에 발생할 때 나타납니다. 이 시점에서 브라우저는 이미 어떤 테마를 표시할지 결정했으며, 당신의 코드는 첫 번째 렌더링 이전에 영향을 미치기에 너무 늦게 도착합니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_왜_클래식_스크립트가_충분하지_않을까요">왜 클래식 스크립트가 충분하지 않을까요?</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_직관적이지만_비효율적인_접근">직관적이지만 비효율적인 접근</h3> <div class="paragraph"> <p>개발자에게 가장 자연스러운 접근법은 스크립트를 우리의 끝에 배치하는 것이다.`<body>`사용자가 선호하는 테마를 확인하고 적용합니다. 이 접근 방식은 페이지 렌더링을 차단하지 않기 위해 스크립트를 페이지 끝에 로드하도록 권장하는 전통적인 웹 모범 사례를 따릅니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">// À la fin de <body> - L'APPROCHE INSUFFISANTE document.addEventListener('DOMContentLoaded', () => { const theme = localStorage.getItem('preferred-theme'); if (theme === 'dark') { document.documentElement.setAttribute('data-bs-theme', 'dark'); } });</code></pre> </div> </div> <div class="paragraph"> <p>이 접근 방식은 처음 보면 논리적으로 보입니다. 우리는 DOM이 준비될 때까지 기다렸다가 테마를 적용합니다. 간단하죠? 불행히도, 이 간결함은 브라우저 렌더링 사이클의 타이밍과 관련된 근본적인 결함을 숨깁니다.</p> </div> </div> <div class="sect2"> <h3 id="_domcontentloaded_이벤트_이해">DOMContentLoaded 이벤트 이해</h3> <div class="paragraph"> <p>이벤트`DOMContentLoaded`초기 HTML 문서가 브라우저에 의해 완전히 로드되고 분석될 때 트리거됩니다,<strong>기다리지 않고</strong>스타일시트, 이미지 및 하위 프레임 로딩이 완료되는 시점입니다. 이는 이해해야 할 중요한 점입니다.</p> </div> <div class="paragraph"> <p>다음은 전형적인 사건의 순서 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>브라우저가 HTML 다운로드를 시작합니다.</p> </li> <li> <p>수신되는 대로 HTML을 분석합니다.</p> </li> <li> <p>그는 태그를 발견한다.`<link>`CSS용이고 다운로드를 시작합니다</p> </li> <li> <p>그는 태그를 발견한다`<script>`그리고 그것들을 실행합니다 (그들의 유형과 속성에 따라)</p> </li> <li> <p>그는 DOM(문서 개체 모델)을 구축합니다.</p> </li> <li> <p><strong>이벤트 `DOMContentLoaded`가 발생합니다</strong></p> </li> <li> <p>그는 스타일을 계속 적용하고 레이아웃을 구성한다</p> </li> <li> <p>첫 번째 페인트(표시) 발생</p> </li> <li> <p>이벤트`load`모두 로드될 때 트리거됩니다</p> </li> </ol> </div> <div class="paragraph"> <p>문제? DOMContentLoaded(6단계)와 첫 페인트(8단계) 사이에 브라우저는 페이지를 어떻게 표시할지 이미 결정을 내렸습니다. 테마 변경 스크립트가 6단계에서 실행되면, 기본 스타일로 첫 번째 표시를 피하기엔 이미 너무 늦습니다.</p> </div> </div> <div class="sect2"> <h3 id="_렌더_블로킹_문제">렌더 블로킹 문제</h3> <div class="paragraph"> <p>사실, 타이밍은 더욱 복잡합니다. 최신 브라우저는 인식된 성능을 개선하기 위해 정교한 최적화 기법을 사용합니다. 사용자가 화면에 무언가를 볼 수 있도록 첫 번째 페인트(First Contentful Paint)를 가능한 한 빠르게 수행하려고 합니다.</p> </div> <div class="paragraph"> <p>CSS는 기본적으로 "render-blocking"입니다. 즉, 브라우저는 첫 번째 페인트를 수행하기 전에 스타일시트를 다운로드하고 파싱할 때까지 기다린다는 의미입니다. 이는 논리적입니다: 스타일이 적용되지 않은 콘텐츠를 표시하고 싶지 않기 때문입니다.</p> </div> <div class="paragraph"> <p>그런데 여기서 함정이 있습니다 : 브라우저가 이 CSS 스타일을 처음 적용할 때, 현재 DOM 상태를 기준으로 그렇게 합니다. 만약 속성`data-bs-theme`태그에 아직 정의되지 않았습니다.<code><html></code>, 브라우저는 기본 스타일을 적용할 것입니다 (보통은 라이트 테마).</p> </div> <div class="paragraph"> <p>그다음에, 스크립트가 실행되어 이 속성을 변경하면, 브라우저는 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>이 변경에 영향을 받는 모든 스타일을 다시 계산합니다</p> </li> <li> <p>필요하다면 레이아웃을 다시 구성하세요.</p> </li> <li> <p>영향을 받은 요소들을 다시 칠하기</p> </li> </ol> </div> <div class="paragraph"> <p>이 재계산 및 재페인트 과정은 보이는 깜박임을 일으키는 것입니다.</p> </div> </div> <div class="sect2"> <h3 id="_문제_시각화">문제 시각화</h3> <div class="paragraph"> <p>이 문제 있는 시퀀스를 더 잘 이해하기 위해 상세한 시퀀스 다이어그램을 살펴보겠습니다 :</p> </div> <div id="diag-flux-incorrect" class="listingblock"> <div class="content"> <pre>@startuml actor Utilisateur participant Navigateur participant "HTML 파서" as Parser participant "CSSOM" as CSS participant "Script.js (body 끝)" as Script participant "렌더링 엔진" as Render Utilisateur -> Navigateur: Demande la page activate Navigateur Navigateur -> Parser: Parse le HTML activate Parser Parser -> CSS: Découvre et charge les CSS activate CSS Parser -> Parser: Construit le DOM Parser -> Navigateur: DOM Ready (DOMContentLoaded) deactivate Parser CSS -> CSS: Parse les feuilles de style CSS -> Render: CSSOM Ready deactivate CSS activate Render Render -> Render: Calcule les styles avec data-bs-theme=""note right: 기본 테마 (light) Render -> Navigateur: 첫 번째 페인트 (라이트 테마) note right: 사용자는 라이트 테마를 본다 deactivate Render Navigateur -> Script: 스크립트를 실행한다 activate Script Script -> Script: localStorage를 읽는다 Script -> Navigateur: `setAttribute('data-bs-theme', 'dark')` deactivate Script activate Render Render -> Render: 스타일을 재계산하고 data-bs-theme="dark" note right: Thème sombre Render -> Navigateur: Repaint (Thème Sombre) note right: Clignotement visible deactivate Render deactivate Navigateur @enduml</pre> </div> </div> <div class="paragraph"> <p>이 다이어그램은 문제를 명확히 보여줍니다: 첫 번째 페인트는 우리 스크립트가 올바른 테마를 정의할 기회가 있기 전에 발생합니다. 이어지는 리페인트가 보이는 깜박임을 유발합니다.</p> </div> </div> <div class="sect2"> <h3 id="_효과_없는_해결_시도들">효과 없는 해결 시도들</h3> <div class="paragraph"> <p>여러 가지 접근 방식이 이 문제를 해결하기 위해 시도되었지만, 대부분 각각의 단점이 있다:</p> </div> <div class="paragraph"> <p><strong>방법 1 : 로드될 때까지 콘텐츠 숨기기</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">body { opacity: 0; transition: opacity 0.3s; } body.loaded { opacity: 1; }</code></pre> </div> </div> <div class="paragraph"> <p>이 접근 방식은 JavaScript가 올바른 테마를 설정할 때까지 모든 콘텐츠를 숨깁니다. 문제점? 이는 콘텐츠 표시를 인위적으로 지연시켜 사이트가 더 느리게 느껴지게 만듭니다. 게다가 JavaScript가 비활성화되면 사용자는 아무것도 보지 못합니다!</p> </div> <div class="paragraph"> <p><strong>방법 2: 로더/스피너 사용</strong></p> </div> <div class="paragraph"> <p>Approach 1과 유사하지만, 로딩 스피너가 있습니다. 이는 문제를 가릴 뿐 실제 성능을 개선하지 않고 불필요한 지각적 지연만 추가합니다.</p> </div> <div class="paragraph"> <p><strong>방법 3: 어두운 테마로 기본 설정</strong></p> </div> <div class="paragraph"> <p>일부 개발자는 CSS에서 다크 테마를 기본값으로 설정합니다. 이로 인해 다크 테마 사용자의 깜빡임을 방지하지만, 라이트 테마 사용자에게는 반대로 문제를 일으킵니다.</p> </div> <div class="paragraph"> <p>이러한 접근 방식 중 어느 것도 만족스럽지 않으며, 그것들은 문제의 근본 원인이 아닌 증상을 다루기 때문입니다.</p> </div> </div> <div class="sect2"> <h3 id="_진정한_해결책_더_빨리_행동하기">진정한 해결책 : 더 빨리 행동하기</h3> <div class="paragraph"> <p>이 문제를 해결하는 열쇠는 해당 속성을 정의해야 함을 깨닫는 것`data-bs-theme` <strong>전에</strong>브라우저가 CSS 스타일을 적용하기 시작하지 않습니다. 이는 우리 스크립트가 페이지 수명 주기에서 더 일찍 실행되어야 함을 의미하며, 이것이 바로 다음 섹션에서 탐구할 내용입니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_해결책_사전_로딩_early_loading">해결책 : 사전 로딩 (Early Loading)</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_기본_원칙">기본 원칙</h3> <div class="paragraph"> <p>우리 문제의 깜박임에 대한 우아한 해결책은 간단하지만 강력한 원리에 기반을 둡니다 :<strong>애플리케이션의 상태를 브라우저의 렌더링 프로세스와 동기화하다</strong>. 페이지가 로드될 때까지 기다리는 대신 테마를 설정해야 하며, 이를 설정해야 합니다.<strong>동안</strong>로드 중, 심지어 CSS 스타일이 적용되기도 전에.</p> </div> <div class="paragraph"> <p>이 접근법은 웹 개발 용어에서 'Early Loading' 또는 'Synchronous Preloading’이라고 부릅니다. 아이디어는 페이지 생명주기에서 가능한 가장早く 우리 테마 감지 로직을 실행하는 것인데, 이상적으로는 태그에서`<head>`, 브라우저가 CSS 파일을 다운로드하기 시작하기 전에도.</p> </div> </div> <div class="sect2"> <h3 id="_왜_head가_이상적인_장소인가">왜 `<head>`가 이상적인 장소인가?</h3> <div class="paragraph"> <p>Le `<head>`HTML 문서는 브라우저에 의해 위에서 아래로 순차적으로 처리됩니다. 각 요소는 나타나는 순서대로 처리됩니다. 이 특성은 우리의 해결책에 매우 중요합니다.</p> </div> <div class="paragraph"> <p>브라우저가 태그를 만나면`<script>`안에`<head>`속성 없이`async` ou <code>defer</code>, il :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>HTML 파싱을 중단합니다</strong></p> </li> <li> <p><strong>스크립트를 다운로드해</strong>(외부인 경우) 또는 침대 (인라인인 경우)</p> </li> <li> <p><strong>즉시 스크립트를 실행해</strong></p> </li> <li> <p><strong>HTML 구문 분석을 재개합니다</strong></p> </li> </ol> </div> <div class="paragraph"> <p>이 행동은 일반적으로 성능 문제로 간주됨(따라서 스크립트를 페이지 끝에 배치하는 것이 일반적인 권장 사항임)이며, 이 특정 경우에 우리의 아군이 됩니다. 우리 테마 감지 스크립트를 페이지 시작에 배치함으로써`<head>`, 우리는それが 브라우저가 태그를 만나기 전에 실행된다고 보장합니다.`<link>`우리 스타일 시트의</p> </div> </div> <div class="sect2"> <h3 id="_3층_솔루션_아키텍처">3층 솔루션 아키텍처</h3> <div class="paragraph"> <p>당사의 완전한 솔루션은 세 가지 서로 의존적인 층으로 구성되어 있으며, 각 층은 특정한 역할을 담당합니다 :</p> </div> <div class="paragraph"> <p><strong>레이어 1 : 지속성 (localStorage)</strong> 이 레이어는 세션 간 사용자의 선택 저장 및 복구를 담당한다.</p> </div> <div class="paragraph"> <p><strong>2 계층: 조기 동기화 (인라인 스크립트 <code><head></code> 내)</strong> 이 레이어는 초기 렌더링 전에 애플리케이션의 상태를 DOM과 동기화합니다.</p> </div> <div class="paragraph"> <p><strong>레이어 3 : 반응형 스타일 (CSS 속성 선택자)</strong> 이 레이어는 레이어 2에서 정의된 상태를 기반으로 시각적 스타일을 정의합니다.</p> </div> <div class="paragraph"> <p>이제 각 층을 자세히 탐구해 봅시다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_단계_1_사용자_선택_저장">단계 1 : 사용자 선택 저장</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_localstorage_당신의_지속적인_메모리">localStorage : 당신의 지속적인 메모리</h3> <div class="paragraph"> <p>Le <code>localStorage`는 브라우저에 키-값 쌍을 지속적으로 저장할 수 있는 웹 스토리지 API입니다. 쿠키와 달리, 데이터의`localStorage</code> :</p> </div> <div class="ulist"> <ul> <li> <p>절대 자동으로 서버에 전송되지 않습니다.</p> </li> <li> <p>더 큰 저장 용량을 가지고 있습니다(일반적으로 5-10MB)</p> </li> <li> <p>만료 날짜가 없습니다(명시적 삭제까지 지속됨)</p> </li> <li> <p>프로토콜과 도메인에 제한됩니다 (Same-Origin Policy)</p> </li> </ul> </div> <div class="paragraph"> <p>우리의 사용 사례에 대해`localStorage`완벽합니다. 왜냐하면:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>우리는 서버에 이 정보를 공유할 필요가 없습니다.</p> </li> <li> <p>우리는 선호가 무기한 지속되기를 원합니다.</p> </li> <li> <p>필요한 저장 공간은 최소(몇 바이트)입니다.</p> </li> </ol> </div> </div> <div class="sect2"> <h3 id="_테마_백업_구현">테마 백업 구현</h3> <div class="paragraph"> <p>다음은 사용자가 테마를 변경할 때 사용자 선택을 저장하는 방법입니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">// Fonction complète pour changer le thème function setTheme(newTheme) { // Validation de l'entrée if (!['light', 'dark', 'auto'].includes(newTheme)) { console.error('Thème invalide:', newTheme); return; } try { // Sauvegarde dans localStorage localStorage.setItem('preferred-theme', newTheme); // Application immédiate dans le DOM document.documentElement.setAttribute('data-bs-theme', newTheme); // Dispatch d'un événement personnalisé pour notifier d'autres composants window.dispatchEvent(new CustomEvent('theme-changed', { detail: { theme: newTheme } })); console.log('Thème changé:', newTheme); } catch (error) { console.error('Erreur lors de la sauvegarde du thème:', error); // Fallback : on applique quand même le thème visuellement document.documentElement.setAttribute('data-bs-theme', newTheme); } } // Exemple d'utilisation avec un bouton document.getElementById('theme-toggle').addEventListener('click', () => { const currentTheme = document.documentElement.getAttribute('data-bs-theme') || 'light'; const newTheme = currentTheme === 'light' ? 'dark' : 'light'; setTheme(newTheme); });</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_오류_케이스_관리">오류 케이스 관리</h3> <div class="paragraph"> <p>필수적으로 관리해야 하는 경우에 대한`localStorage`는 사용할 수 없거나 접근할 수 없습니다. 여러 시나리오가 접근을 차단할 수 있습니다.<code>localStorage</code>:</p> </div> <div class="paragraph"> <p><strong>엄격한 개인 정보 보호 브라우징</strong>: Safari가 비공개 모드에서 예외를 발생시킵니다`QuotaExceededError`쓰는 시도 중`localStorage`.</p> </div> <div class="paragraph"> <p><strong>프라이버시 설정</strong>: 일부 브라우저 또는 개인정보 보호 확장 프로그램은 액세스를 차단할 수 있습니다.<code>localStorage</code>.</p> </div> <div class="paragraph"> <p><strong>도메인 제한</strong> : Le `localStorage`프로토콜에서 접근할 수 없습니다`file://`일부 브라우저에서.</p> </div> <div class="paragraph"> <p><strong>저장 공간이 포화 상태입니다.</strong>드물기는 하지만 저장 공간이 완전히 가득 차게 될 수 있습니다.</p> </div> <div class="paragraph"> <p>그래서 우리 코드는 블록을 사용합니다.`try…​catch`이러한 경우를 우아하게 처리하기 위해, 지속성이 제공되지 않더라도 테마 변경 기능을 계속 제공합니다.</p> </div> </div> <div class="sect2"> <h3 id="_고급_지속성_전략">고급 지속성 전략</h3> <div class="paragraph"> <p>더 정교한 애플리케이션을 위해 추가 전략을 고려할 수 있습니다:</p> </div> <div class="paragraph"> <p><strong>서버 동기화 (선택 사항)</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">async function setTheme(newTheme) { // Sauvegarde locale immédiate localStorage.setItem('preferred-theme', newTheme); document.documentElement.setAttribute('data-bs-theme', newTheme); // Synchronisation serveur en arrière-plan (si l'utilisateur est connecté) if (userIsAuthenticated()) { try { await fetch('/api/user/preferences', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ theme: newTheme }) }); } catch (error) { console.warn('Échec de la synchronisation serveur:', error); // L'échec n'est pas critique car la préférence est déjà sauvegardée localement } } }</code></pre> </div> </div> <div class="paragraph"> <p>이 접근 방식은 로그인된 사용자를 위해 기기 간 선호도를 동기화하면서도 즉각적인 로컬 응답성을 유지합니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_단계_2_head_내의_프리로드_스크립트">단계 2: <code><head></code> 내의 프리로드 스크립트</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_해결책의_핵심">해결책의 핵심</h3> <div class="paragraph"> <p>여기가 진정으로 마법이 일어나는 곳입니다. 우리는 작은 스크립트를 배치할 것입니다.<strong>인라인</strong>우리 안에 직접적으로`<head>`, 모든 우리 태그 앞에`<link>`스타일시트. 이 스크립트는 의도적으로 최소화되고 독립적이며, 가능한 한 빠르게 실행되도록 설계되었습니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Mon Site Incroyable</title> <!-- ========================================== NOTRE SCRIPT MAGIQUE DE PRÉ-CHARGEMENT Ce script DOIT être le premier élément dans le <head> après les meta tags ========================================== --> <script> // IIFE pour ne pas polluer le scope global (function() { 'use strict'; try { // Lecture de la préférence sauvegardée const savedTheme = localStorage.getItem('preferred-theme'); // Si une préférence existe, on l'applique immédiatement if (savedTheme) { document.documentElement.setAttribute('data-bs-theme', savedTheme); } // Optionnel : Détecter la préférence système si aucune sauvegarde else if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) { document.documentElement.setAttribute('data-bs-theme', 'dark'); } // Sinon, le thème par défaut du CSS sera utilisé (généralement 'light') } catch (error) { // En cas d'erreur (localStorage bloqué, etc.), on log discrètement // et on laisse le thème par défaut s'appliquer console.warn('Impossible de charger la préférence de thème:', error); } })(); </script> <!-- FIN DU SCRIPT MAGIQUE --> <!-- Les feuilles de style sont chargées APRÈS le script --> <link rel="stylesheet" href="css/bootstrap.min.css"> <link rel="stylesheet" href="css/styles.css"> <!-- Autres ressources du head --> <link rel="icon" href="favicon.ico"> </head> <body> <!-- Contenu de la page --> </body> </html></code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_스크립트_해부_모든_라인이_중요">스크립트 해부: 모든 라인이 중요</h3> <div class="paragraph"> <p>이 스크립트를 한 줄씩 분석하여 각 디자인 결정을 이해해 봅시다:</p> </div> <div class="paragraph"> <p><strong>즉시 실행 함수 표현(IIFE)</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">(function() { // ... })();</code></pre> </div> </div> <div class="paragraph"> <p>이 구조는 즉시 실행되는 함수를 만든다. 왜? 로컬 스코프에서 변수를 격리하여 전역 스코프를 오염시키지 않기 위해서다. 우리가 단지 사용하고 있을 뿐이라도`const`(블록 스코프를 가지는), IIFE는 우리의 의도를 명확히 하고 이름 충돌을 방지하는 좋은 관행입니다.</p> </div> <div class="paragraph"> <p><strong>엄격 모드</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">'use strict';</code></pre> </div> </div> <div class="paragraph"> <p>이 지시문은 JavaScript의 엄격 모드를 활성화합니다, 이는 : 미선언된 변수 사용을 금지합니다. - 위험한 작업에 대한 오류를 발생시킵니다 - 특정 JavaScript 엔진에서 성능을 향상시킵니다.</p> </div> <div class="paragraph"> <p>중요한 스크립트인 경우에는 최대 보안을 원합니다.</p> </div> <div class="paragraph"> <p><strong>try…​catch 블록</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">try { // Code principal } catch (error) { console.warn('Impossible de charger la préférence de thème:', error); }</code></pre> </div> </div> <div class="paragraph"> <p>이 블록은 절대적으로 중요합니다. 이는 어떤 문제가 발생하더라도 (localStorage 차단, improb한 문법 오류, 등), 우리의 스크립트가 전체 페이지 로드를 차단하지 않음을 보장합니다. 사용법은`console.warn`보다는`console.error`이는 비중요한 문제임을 나타냅니다.</p> </div> <div class="paragraph"> <p><strong>localStorage 읽기</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">const savedTheme = localStorage.getItem('preferred-theme');</code></pre> </div> </div> <div class="paragraph"> <p>이 줄은 일부 컨텍스트(사파리의 엄격한 사적 브라우징)에서 예외를 발생시킬 수 있습니다. 이것이 바로 이 줄이 try…​catch 블록 안에 있는 이유입니다.</p> </div> <div class="paragraph"> <p><strong>조건부 적용</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">if (savedTheme) { document.documentElement.setAttribute('data-bs-theme', savedTheme); }</code></pre> </div> </div> <div class="paragraph"> <p>주제를 저장된 것을 찾았을 경우에만 적용하고, 그렇지 않으면 CSS가 기본 테마를 사용하도록 둡니다. 이 접근 방식은 자바스크립트에 하드코딩된 기본 값보다 더 견고합니다.</p> </div> </div> <div class="sect2"> <h3 id="_시스템_선호도_감지_보너스">시스템 선호도 감지 (보너스)</h3> <div class="paragraph"> <p>선택 사항이지만 우아한 개선 사항은 사용자가 아직 앱에서 명시적인 선택을 하지 않은 경우 운영 체제의 테마 선호도를 감지하는 것입니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">else if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) { document.documentElement.setAttribute('data-bs-theme', 'dark'); }</code></pre> </div> </div> <div class="paragraph"> <p>이 기능은 미디어 쿼리를 사용합니다.`prefers-color-scheme`시스템을 쿼리하기 위해. macOS, Windows 10+, iOS, 그리고 최신 Android에서 이 쿼리는 사용자의 시스템 기본 설정을 반환합니다.</p> </div> <div class="paragraph"> <p><strong>장점 :</strong> 첫 방문부터 맞춤형 경험 사용자 시스템 환경과의 일관성 - 첫 번째 방문에는 저장소가 필요 없습니다.</p> </div> <div class="paragraph"> <p><strong>고려 사항:</strong> - 모든 브라우저가 이 기능을 지원하지는 않습니다(하지만 2020년부터 지원이 뛰어납니다) - 검증`window.matchMedia`호환성을 보장합니다 - 사용자는 언제든지 이 선택을 재정의할 수 있습니다.</p> </div> </div> <div class="sect2"> <h3 id="_성능_왜_이_스크립트는_빠른가">성능 : 왜 이 스크립트는 빠른가</h3> <div class="paragraph"> <p>우리의 사전 로딩 스크립트는 매우 빠르게 설계되었습니다 :</p> </div> <div class="paragraph"> <p><strong>최소 크기</strong>: 약 300바이트(비압축), 200바이트(압축). 이미지나 JavaScript 라이브러리와 비교했을 때 무시할 수 있을 정도입니다.</p> </div> <div class="paragraph"> <p><strong>인라인</strong>추가 HTTP 요청이 없습니다. 스크립트는 HTML 내에 있으므로 즉시 사용 가능합니다.</p> </div> <div class="paragraph"> <p><strong>간단한 동기식 작업</strong>: 로컬스토리지의 키 읽기 (초고속 작업) 및 DOM 속성 수정 (브라우저 네이티브 작업).</p> </div> <div class="paragraph"> <p><strong>의존성이 없습니다.</strong>: 프레임워크도, 라이브러리도 없이 바닐라 자바스크립트만. 시작 시간도, 의존성 파싱도 없습니다.</p> </div> <div class="paragraph"> <p><strong>단일 실행</strong>이 스크립트는 로드 시 한 번만 실행됩니다. 이벤트 리스너도, 루프도, 복잡한 계산도 없습니다.</p> </div> <div class="paragraph"> <p>실제로 현대 하드웨어에서는 이 스크립트가 1밀리초 미만으로 실행되며, 이는 페이지 로드 성능에 전혀 영향을 주지 않는 거의 느낄 수 없는 시간이다.</p> </div> </div> <div class="sect2"> <h3 id="_head_안에_최적의_배치"><head>` 안에 최적의 배치</h3> <div class="paragraph"> <p>요소들의 순서가`<head>`중요합니다. 권장 순서는 다음과 같습니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><head> <!-- 1. Métadonnées critiques --> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <!-- 2. Notre script de pré-chargement (IMMÉDIATEMENT après les meta) --> <script> (function() { /* notre code */ })(); </script> <!-- 3. Titre de la page --> <title>Mon Site</title> <!-- 4. Feuilles de style --> <link rel="stylesheet" href="styles.css"> <!-- 5. Autres ressources (fonts, favicons, etc.) --> <link rel="preconnect" href="https://fonts.googleapis.com"> <link rel="icon" href="favicon.ico"> <!-- 6. Autres scripts avec defer ou async --> <script src="app.js" defer></script> </head></code></pre> </div> </div> <div class="paragraph"> <p>이 주문은 다음을 보장합니다 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>문자 집합은 텍스트 처리 전에 정의됩니다.</p> </li> <li> <p>우리 스크립트는 CSS가 로드되기 전에 실행됩니다.</p> </li> <li> <p>CSS는 나중에 로드되어 올바른 테마를 직접 적용합니다.</p> </li> <li> <p>다른 비중요한 리소스는 마지막으로 로드됩니다.</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_단계_3_css_속성_선택자의_힘">단계 3 : CSS 속성 선택자의 힘</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_bootstrap_5_테마_시스템">Bootstrap 5 테마 시스템</h3> <div class="paragraph"> <p>Bootstrap 5는 CSS 커스텀 속성(변수)과 속성 선택자를 기반으로 하는 우아한 테마 관리 시스템을 도입했습니다. 이 시스템은 속성을`data-bs-theme`요소 위`<html>`적용할 색 변수 세트를 결정하기 위해</p> </div> <div class="paragraph"> <p>이 시스템의 아름다움은 그 단순함에 있다: 수천 개의 요소에 대한 다양한 스타일시트를 로드하거나 클래스를 토글하는 대신, 단일 요소의 속성만 바꾸면 CSS가 캐스케이드를 통해 나머지를 처리한다.</p> </div> </div> <div class="sect2"> <h3 id="_테마_시스템을_위한_css_구조">테마 시스템을 위한 CSS 구조</h3> <div class="paragraph"> <p>다음은 견고한 테마 시스템을 구현하기 위한 완전한 CSS 구조입니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">/** * SYSTÈME DE THÈME COMPLET * Utilise les Custom Properties CSS pour une maintenance facile */ /* ============================================ THÈME PAR DÉFAUT (LIGHT) Défini sur :root pour être le fallback ============================================ */ :root { /* Couleurs de base */ --color-primary: #0d6efd; --color-secondary: #6c757d; --color-success: #198754; --color-danger: #dc3545; --color-warning: #ffc107; --color-info: #0dcaf0; /* Couleurs de fond */ --bg-primary: #ffffff; --bg-secondary: #f8f9fa; --bg-tertiary: #e9ecef; /* Couleurs de texte */ --text-primary: #212529; --text-secondary: #6c757d; --text-tertiary: #adb5bd; /* Couleurs de bordure */ --border-color: #dee2e6; --border-color-subtle: #e9ecef; /* Couleurs d'ombre */ --shadow-sm: rgba(0, 0, 0, 0.075); --shadow-md: rgba(0, 0, 0, 0.15); --shadow-lg: rgba(0, 0, 0, 0.25</code></pre> </div> </div> </div> </div> </div> https://cheroliv.com/blog/2025/0097_gradle_plugin_dev_func_test_logger_post.html Fri, 7 Nov 2025 00:00:00 +0000 blog/2025/0097_gradle_plugin_dev_func_test_logger_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_소개">소개</a></li> <li><a href="#_문제_gradlerunner_의존성">문제: GradleRunner 의존성</a> <ul class="sectlevel2"> <li><a href="#_플러그인_개발의_맥락">플러그인 개발의 맥락</a></li> <li><a href="#_로깅_딜레마">로깅 딜레마</a></li> <li><a href="#_잘못된_좋은_생각들">잘못된 좋은 생각들</a></li> </ul> </li> <li><a href="#_해결책_독립_로거">해결책: 독립 로거</a> <ul class="sectlevel2"> <li><a href="#_추천_아키텍처">추천 아키텍처</a></li> <li><a href="#_실행_흐름">실행 흐름</a></li> </ul> </li> <li><a href="#_완전_구현">완전 구현</a> <ul class="sectlevel2"> <li><a href="#_gradle_의존성">Gradle 의존성</a></li> <li><a href="#_logback_구성">Logback 구성</a></li> <li><a href="#_완전한_테스트_클래스">완전한 테스트 클래스</a></li> </ul> </li> <li><a href="#_다단계_로깅_스키마">다단계 로깅 스키마</a></li> <li><a href="#_모범_사례">모범 사례</a> <ul class="sectlevel2"> <li><a href="#_권장_로깅_구조">권장 로깅 구조</a></li> <li><a href="#_가독성을_위한_시각적_상징">가독성을 위한 시각적 상징</a></li> <li><a href="#_출력에서_정보_추출">출력에서 정보 추출</a></li> </ul> </li> <li><a href="#_전후_비교">전/후 비교</a> <ul class="sectlevel2"> <li><a href="#_이전_문제적_접근">이전 : 문제적 접근</a></li> <li><a href="#_후_강건한_접근법">후: 강건한 접근법</a></li> </ul> </li> <li><a href="#_요약도">요약도</a></li> <li><a href="#_피해야_할_함정">피해야 할 함정</a> <ul class="sectlevel2"> <li><a href="#_함정_1번_잊기_forwardoutput">❌ 함정 1번 : 잊기 `.forwardOutput()</a></li> <li><a href="#_함정_2번_초기화되지_않은_로거">❌ 함정 2번 : 초기화되지 않은 로거</a></li> <li><a href="#_함정_3번_과도한_로깅">❌ 함정 3번 : 과도한 로깅</a></li> </ul> </li> <li><a href="#_결과_및_지표">결과 및 지표</a></li> <li><a href="#_결론">결론</a></li> <li><a href="#_자원">자원</a></li> <li><a href="#_더_멀리_가다">더 멀리 가다</a></li> </ul> </div> <div class="sect1"> <h2 id="_소개">소개</h2> <div class="sectionbody"> <div class="paragraph"> <p>Gradle 플러그인을 개발하는 동안, 기능 테스트는 실제 Gradle 환경에서 플러그인의 동작을 검증하는 데 필수적입니다. 그러나 중요한 질문이 빠르게 제기됩니다:<strong>어떻게 `GradleRunner`와 문제의존성을 만들지 않고 효과적인 로깅 시스템을 설정할 수 있나요?</strong></p> </div> <div class="paragraph"> <p>이 글에서 탐구할 것:</p> </div> <div class="ulist"> <ul> <li> <p>Gradle 기능 테스트에서의 로깅 문제</p> </li> <li> <p>SLF4J과 Logback을 사용한 견고한 솔루션의 아키텍처</p> </li> <li> <p>완전한 구현과 구체적인 예시</p> </li> <li> <p>좋은 관행과 피해야 할 함정</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_문제_gradlerunner_의존성">문제: GradleRunner 의존성</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_플러그인_개발의_맥락">플러그인 개발의 맥락</h3> <div class="paragraph"> <p>그레이들 플러그인을 개발할 때 일반적으로 를 사용합니다`GradleRunner`<em>Gradle TestKit</em> 로 테스트 빌드를 실행 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `test my plugin`() { val result = GradleRunner.create() .withProjectDir(projectDir) .withArguments("myTask") .build() // Comment logger efficacement ici ? }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_로깅_딜레마">로깅 딜레마</h3> <div class="paragraph"> <p>주요 문제는 다음과 같습니다:<strong>로깅은 초기화 여부가 확실하지 않은 객체에 의존해서는 안 된다</strong>.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml !define RECTANGLE class skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "문제적인 아키텍처" { RECTANGLE Test { + runTest() } RECTANGLE GradleRunner { + build() + getLogger() ❌ } RECTANGLE Logger { + info() + debug() } Test --> GradleRunner : dépend de Logger ..> GradleRunner : dépend de ❌ } note right of Logger Problème: Le logger dépend du GradleRunner qui peut ne pas être initialisé end note @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_잘못된_좋은_생각들">잘못된 좋은 생각들</h3> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>하지 마세요 :</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// ❌ MAUVAIS: Tentative d'obtenir un logger du runner val runner = GradleRunner.create() val logger = runner.logger // N'existe pas ! // ❌ MAUVAIS: Logger partagé initialisé tardivement lateinit var logger: Logger @BeforeEach fun setup() { logger = LoggerFactory.getLogger(...) }</code></pre> </div> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_해결책_독립_로거">해결책: 독립 로거</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_추천_아키텍처">추천 아키텍처</h3> <div class="paragraph"> <p>해결책은 로거를 사용하는 것입니다.<strong>완전히 독립적인</strong> du <code>GradleRunner</code>, 테스트 클래스 수준에서 초기화된.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml !define RECTANGLE class skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "올바른 아키텍처" { RECTANGLE TestClass { + {static} logger: Logger ✓ + runTest() } RECTANGLE SLF4J { + LoggerFactory } RECTANGLE GradleRunner { + build() + forwardOutput() } RECTANGLE "콘솔 출력" as Output { + captured text } TestClass --> SLF4J : utilise ✓ TestClass --> GradleRunner : utilise GradleRunner --> Output : génère TestClass --> Output : analyse } note top of TestClass Le logger est initialisé indépendamment du GradleRunner end note note bottom of GradleRunner .forwardOutput() permet de capturer la sortie pour analyse end note @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_실행_흐름">실행 흐름</h3> <div class="listingblock"> <div class="content"> <pre>@startuml !theme plain skinparam backgroundColor #FEFEFE participant "JUnit" as junit participant "테스트클래스" as test participant "로거 (SLF4J)" as logger participant "GradleRunner" as runner participant "Gradle 빌드" as gradle activate junit junit -> test : load class activate test test -> logger : initialize (companion) activate logger logger --> test : logger ready ✓ deactivate logger junit -> test : @BeforeAll test -> logger : info("Initialisation...") junit -> test : @BeforeEach test -> logger : debug("세트업 테스트...") junit -> test : @Test test -> logger : info("시작 중...") test -> runner : create() activate runner test -> runner : .forwardOutput() test -> runner : .withArguments(...) test -> runner : .build() runner -> gradle : execute build activate gradle gradle --> runner : output text deactivate gradle runner --> test : BuildResult + output deactivate runner test -> logger : debug("출력 분석 중...") test -> test : analyze output test -> logger : info("✓ 테스트 통과") test --> junit : success deactivate test deactivate junit @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_완전_구현">완전 구현</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_gradle_의존성">Gradle 의존성</h3> <div class="paragraph"> <p>필요한 종속성을 추가하세요`build.gradle.kts`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">dependencies { // Pour les tests fonctionnels testImplementation(gradleTestKit()) testImplementation("org.junit.jupiter:junit-jupiter:5.10.2") // Pour le logging testImplementation("org.slf4j:slf4j-api:2.0.17") testRuntimeOnly("ch.qos.logback:logback-classic:1.4.14") // Pour les assertions testImplementation("org.assertj:assertj-core:3.27.6") } tasks.test { useJUnitPlatform() }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_logback_구성">Logback 구성</h3> <div class="paragraph"> <p>파일을 만드세요`src/test/resources/logback-test.xml` :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><?xml version="1.0" encoding="UTF-8"?> <configuration> <!-- Appender console avec format lisible --> <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <encoder> <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern> </encoder> </appender> <!-- Appender fichier pour conservation --> <appender name="FILE" class="ch.qos.logback.core.FileAppender"> <file>build/test-results/functional-tests.log</file> <encoder> <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n</pattern> </encoder> </appender> <!-- Logger pour vos tests --> <logger name="com.cheroliv.bakery" level="DEBUG"/> <!-- Réduire le bruit de Gradle --> <logger name="org.gradle" level="WARN"/> <!-- Configuration racine --> <root level="INFO"> <appender-ref ref="STDOUT"/> <appender-ref ref="FILE"/> </root> </configuration></code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_완전한_테스트_클래스">완전한 테스트 클래스</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">package com.cheroliv.bakery import org.gradle.testkit.runner.GradleRunner import org.gradle.testkit.runner.TaskOutcome import org.junit.jupiter.api.* import org.junit.jupiter.api.TestInstance.Lifecycle.PER_CLASS import org.junit.jupiter.api.io.TempDir import org.slf4j.Logger import org.slf4j.LoggerFactory import java.io.File import kotlin.test.assertEquals import kotlin.test.assertTrue @TestInstance(PER_CLASS) class BakeryPluginFunctionalTest { @field:TempDir lateinit var projectDir: File private val buildFile by lazy { projectDir.resolve("build.gradle.kts") } private val settingsFile by lazy { projectDir.resolve("settings.gradle.kts") } companion object { // ✓ Logger indépendant, initialisé au chargement de la classe private val logger: Logger = LoggerFactory.getLogger( BakeryPluginFunctionalTest::class.java ) @JvmStatic @BeforeAll fun globalSetup() { logger.info("═".repeat(60)) logger.info("DÉMARRAGE DE LA SUITE DE TESTS FONCTIONNELS") logger.info("═".repeat(60)) } @JvmStatic @AfterAll fun globalTeardown() { logger.info("═".repeat(60)) logger.info("FIN DE LA SUITE DE TESTS") logger.info("═".repeat(60)) } } @BeforeEach fun setup() { logger.info("─".repeat(60)) logger.info("Préparation de l'environnement de test") logger.debug("Répertoire de test: ${projectDir.absolutePath}") settingsFile.writeText(""" rootProject.name = "test-bakery-project" """.trimIndent()) logger.debug("✓ settings.gradle.kts créé") } @AfterEach fun teardown(testInfo: TestInfo) { logger.info("✓ Test terminé: ${testInfo.displayName}") logger.info("─".repeat(60)) } @Test fun `plugin can be applied successfully`() { logger.info("TEST: Application du plugin Bakery") buildFile.writeText(""" plugins { id("com.cheroliv.bakery") } """.trimIndent()) logger.debug("Fichier build.gradle.kts créé") logger.debug("Lancement du build Gradle...") val startTime = System.currentTimeMillis() val result = GradleRunner.create() .forwardOutput() // ← Important : capture la sortie .withPluginClasspath() .withArguments("tasks", "--group=bakery", "--stacktrace") .withProjectDir(projectDir) .build() val duration = System.currentTimeMillis() - startTime logger.info("Build terminé en ${duration}ms") // Analyse de la sortie logger.debug("Analyse de la sortie Gradle...") val outputLines = result.output.lines() logger.debug("Nombre de lignes capturées: ${outputLines.size}") // Validation val expectedTasks = listOf("bake", "printConfigPath", "printJBakeClasspath") logger.info("Vérification des tâches attendues:") expectedTasks.forEach { task -> val found = result.output.contains(task) logger.debug(" ${if (found) "✓" else "✗"} $task") assertTrue(found, "Task '$task' should be available") } logger.info("✓ Plugin appliqué avec succès - ${expectedTasks.size} tâches trouvées") } @Test fun `bake task executes and prints version`() { logger.info("TEST: Exécution de la tâche 'bake'") buildFile.writeText(""" plugins { id("com.cheroliv.bakery") } """.trimIndent()) logger.debug("Exécution de 'gradle bake'...") val result = GradleRunner.create() .forwardOutput() .withPluginClasspath() .withArguments("bake", "--info") // --info pour plus de détails .withProjectDir(projectDir) .build() // Extraction d'informations depuis la sortie logger.debug("Recherche du message 'Baking site'...") val hasBakingMessage = result.output.contains("Baking site with Bakery Plugin!") logger.debug("Recherche de la version JBake...") val hasVersionMessage = result.output.contains("Using JBake version:") // Extraction de la version (si présente) val versionRegex = Regex("Using JBake version: (.+)") val versionMatch = versionRegex.find(result.output) if (versionMatch != null) { val version = versionMatch.groupValues[1] logger.info("Version JBake détectée: $version") } // Validation assertTrue(hasBakingMessage, "Message 'Baking site' attendu") assertTrue(hasVersionMessage, "Message de version attendu") assertEquals(TaskOutcome.SUCCESS, result.task(":bake")?.outcome) logger.info("✓ Tâche 'bake' exécutée avec succès") } @Test fun `analyze output with structured logging`() { logger.info("TEST: Analyse structurée de la sortie") buildFile.writeText(""" plugins { id("com.cheroliv.bakery") } task("diagnostics") { doLast { println("[DIAG] Project: ${'$'}{project.name}") println("[DIAG] Build dir: ${'$'}{project.buildDir}") println("[DIAG] Plugin applied: true") val config = configurations.findByName("jbakeRuntime") println("[DIAG] JBake config exists: ${'$'}{config != null}") if (config != null) { println("[DIAG] Dependencies count: ${'$'}{config.dependencies.size}") } } } """.trimIndent()) logger.debug("Exécution de la tâche diagnostics...") val result = GradleRunner.create() .forwardOutput() .withPluginClasspath() .withArguments("diagnostics", "--quiet") .withProjectDir(projectDir) .build() // Analyse structurée logger.info("Extraction des informations de diagnostic:") val diagLines = result.output.lines() .filter { it.startsWith("[DIAG]") } logger.debug("Nombre de lignes de diagnostic: ${diagLines.size}") diagLines.forEach { line -> logger.info(" $line") // Analyse spécifique par type de ligne when { line.contains("Project:") -> { val projectName = line.substringAfter("Project:").trim() logger.debug(" → Nom du projet extrait: '$projectName'") } line.contains("Dependencies count:") -> { val count = line.substringAfter("count:").trim() logger.debug(" → Nombre de dépendances: $count") } } } assertTrue(diagLines.isNotEmpty(), "Des lignes de diagnostic devraient être présentes") logger.info("✓ Analyse structurée terminée - ${diagLines.size} lignes analysées") } @Test fun `test with error handling`() { logger.info("TEST: Gestion d'erreurs avec logging") buildFile.writeText(""" plugins { id("com.cheroliv.bakery") } """.trimIndent()) try { logger.debug("Tentative d'exécution...") val result = GradleRunner.create() .forwardOutput() .withPluginClasspath() .withArguments("printJBakeClasspath") .withProjectDir(projectDir) .build() val outcome = result.task(":printJBakeClasspath")?.outcome logger.info("Outcome: $outcome") if (outcome == TaskOutcome.SUCCESS) { logger.info("✓ Exécution réussie") } else { logger.warn("⚠ Outcome inattendu: $outcome") } assertEquals(TaskOutcome.SUCCESS, outcome) } catch (e: Exception) { logger.error("✗ Échec du test", e) logger.error("Type d'exception: ${e.javaClass.simpleName}") logger.error("Message: ${e.message}") // Log de la stack trace si nécessaire if (logger.isDebugEnabled) { logger.debug("Stack trace complète:", e) } throw e } } }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_다단계_로깅_스키마">다단계 로깅 스키마</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>@startuml !theme plain skinparam backgroundColor #FEFEFE package "로깅 레벨" { rectangle "흔적" #E8E8E8 { note Détails d'exécution très fins • Valeurs de variables • Appels de méthodes internes end note } rectangle "디버그" #D0E8FF { note Informations de débogage • Étapes intermédiaires • Contenu des fichiers créés • Analyse de la sortie Gradle end note } rectangle "정보" #C8FFC8 { note Informations principales • Début/fin de test • Résultats de validation • Durée d'exécution end note } rectangle "경고" #FFFFC8 { note Avertissements • Comportements inattendus • Outcomes inhabituels end note } rectangle "오류" #FFC8C8 { note Erreurs • Échecs de test • Exceptions • Stack traces end note } } @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_모범_사례">모범 사례</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_권장_로깅_구조">권장 로깅 구조</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `mon test`() { // 1. LOG: Début du test logger.info("TEST: Description du test") // 2. LOG: Préparation logger.debug("Préparation des fichiers...") buildFile.writeText("...") logger.debug("✓ Fichiers préparés") // 3. LOG: Exécution logger.debug("Lancement du build...") val startTime = System.currentTimeMillis() val result = GradleRunner.create() .forwardOutput() .withArguments("task") .build() val duration = System.currentTimeMillis() - startTime logger.info("Build terminé en ${duration}ms") // 4. LOG: Analyse logger.debug("Analyse des résultats...") // ... validations ... // 5. LOG: Conclusion logger.info("✓ Test réussi") }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_가독성을_위한_시각적_상징">가독성을 위한 시각적 상징</h3> <div class="paragraph"> <p>유니코드 기호를 사용하여 로그의 가독성을 향상시킵니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">logger.info("✓ Succès") logger.info("✗ Échec") logger.info("⚠ Attention") logger.info("→ Étape suivante") logger.info("═".repeat(60)) // Séparateur principal logger.info("─".repeat(60)) // Séparateur secondaire</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_출력에서_정보_추출">출력에서 정보 추출</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// Recherche simple val hasMessage = result.output.contains("Expected message") // Extraction avec regex val versionRegex = Regex("Version: (.+)") val version = versionRegex.find(result.output)?.groupValues?.get(1) // Filtrage de lignes val errorLines = result.output.lines() .filter { it.contains("ERROR") } errorLines.forEach { logger.error("Gradle error: $it") }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_전후_비교">전/후 비교</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_이전_문제적_접근">이전 : 문제적 접근</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class MyTest { lateinit var logger: Logger // ❌ Initialisé tardivement @BeforeEach fun setup() { logger = LoggerFactory.getLogger(...) // ❌ Dépendance } @Test fun test() { val runner = GradleRunner.create() logger.info("Testing...") // ⚠ Peut échouer } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_후_강건한_접근법">후: 강건한 접근법</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class MyTest { companion object { private val logger = LoggerFactory.getLogger(...) // ✓ Indépendant } @Test fun test() { logger.info("TEST: Starting...") // ✓ Toujours disponible val result = GradleRunner.create() .forwardOutput() // ✓ Capture la sortie .build() logger.debug("Output: ${result.output}") // ✓ Analyse } }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_요약도">요약도</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>@startuml !theme plain skinparam backgroundColor #FEFEFE title 기능 테스트에서의 완전한 로깅 흐름 actor "개발자" as dev participant "JUnit" as junit participant "테스트클래스" as test participant "Logger\n(SLF4J)" as logger participant "로그백" as logback participant "GradleRunner" as runner participant "콘솔/파일" as output dev -> junit : lance les tests activate junit junit -> test : charge la classe activate test test -> logger : initialize (companion) activate logger logger -> logback : configure activate logback logback --> logger : ready deactivate logback logger --> test : ✓ deactivate logger == Phase de Setup == junit -> test : @BeforeAll test -> logger : info("초기화") logger -> output : [INFO] Initialisation junit -> test : @BeforeEach test -> logger : debug("설정 테스트") logger -> output : [DEBUG] Setup test == Phase de Test == junit -> test : @Test test -> logger : info("시작") logger -> output : [INFO] TEST: Starting test -> runner : create() activate runner test -> runner : .forwardOutput() test -> runner : .build() runner -> runner : execute Gradle runner --> test : BuildResult + output text deactivate runner test -> logger : debug("출력 분석 중") logger -> output : [DEBUG] Analyzing output test -> test : assertions test -> logger : info("✓ 테스트 통과") logger -> output : [INFO] ✓ Test passed == Phase de Cleanup == junit -> test : @AfterEach test -> logger : debug("정리") logger -> output : [DEBUG] Cleanup junit -> test : @AfterAll test -> logger : info("테스트 종료") logger -> output : [INFO] Fin des tests test --> junit : ✓ all tests passed deactivate test deactivate junit dev <-- junit : rapport de tests @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_피해야_할_함정">피해야 할 함정</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_함정_1번_잊기_forwardoutput">❌ 함정 1번 : 잊기 `.forwardOutput()</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// MAUVAIS: La sortie Gradle n'est pas capturée val result = GradleRunner.create() .withArguments("task") .build() // result.output sera vide !</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// BON: La sortie est capturée val result = GradleRunner.create() .forwardOutput() // ✓ .withArguments("task") .build()</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_함정_2번_초기화되지_않은_로거">❌ 함정 2번 : 초기화되지 않은 로거</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// MAUVAIS class Test { lateinit var logger: Logger // Peut ne pas être initialisé }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// BON class Test { companion object { private val logger = LoggerFactory.getLogger(...) // Toujours initialisé } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_함정_3번_과도한_로깅">❌ 함정 3번 : 과도한 로깅</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// MAUVAIS: Trop de logs DEBUG en production logger.debug("Variable a = $a") logger.debug("Variable b = $b") logger.debug("Variable c = $c") // ... 100 lignes de logs</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// BON: Logging ciblé logger.info("Traitement de ${items.size} éléments") logger.debug("Détails: ${items.take(5)}...") // Échantillon seulement</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_결과_및_지표">결과 및 지표</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 방법을 사용하면 다음과 같은 결과를 얻습니다 :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 28.5714%;"> <col style="width: 42.8571%;"> <col style="width: 28.5715%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">메트릭</th> <th class="tableblock halign-left valign-top">앞에</th> <th class="tableblock halign-left valign-top">이후</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">코드 줄</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~50줄</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~80 라인 (+60%)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">디버그 시간</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~30 분</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~5 min (-83%)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">감지된 오류</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">기본</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">상세한</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">유지보수</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">어렵다</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">간단한</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">독립</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">결합된</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✓ 독립적인</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_결론">결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>Gradle 플러그인의 기능 테스트에서 안정적인 로깅 시스템을 구축하는 것은 간단한 원칙에 기반합니다 :<strong>독립</strong>.</p> </div> <div class="paragraph"> <p>주요 포인트:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>독립형 로거</strong>: 에서 초기화된`companion object`</p> </li> <li> <p><strong>SLF4J와 Logback</strong>: 검증되고 구성 가능한 Stack</p> </li> <li> <p><strong>.forwardOutput()</strong>: Gradle 출력 캡처</p> </li> <li> <p><strong>구조화된 로깅</strong>: INFO 단계용, DEBUG 세부정보용</p> </li> <li> <p><strong>출력 분석</strong>:부터 정보 추출`result.output`</p> </li> </ol> </div> <div class="paragraph"> <p>이 접근 방식은 테스트를 보장합니다.<strong>유지 가능한</strong>, <strong>디버그 가능한</strong> et <strong>튼튼한</strong>, 견고한 설계 원칙을 준수하면서.</p> </div> </div> </div> <div class="sect1"> <h2 id="_자원">자원</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://docs.gradle.org/current/userguide/test_kit.html">Gradle TestKit 문서</a></p> </li> <li> <p><a href="https://www.slf4j.org/manual.html">SLF4J 매뉴얼</a></p> </li> <li> <p><a href="https://logback.qos.ch/manual/configuration.html">Logback 구성</a></p> </li> <li> <p><a href="https://github.com/gradle/gradle/tree/master/subprojects/test-kit">Gradle TestKit 소스 코드</a></p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_더_멀리_가다">더 멀리 가다</h2> <div class="sectionbody"> <div class="paragraph"> <p>곧 다음 기사에서 탐구할 내용:</p> </div> <div class="ulist"> <ul> <li> <p>구조화된 로깅을 사용한 지속적 통합</p> </li> <li> <p>로그가 포함된 HTML 테스트 보고서</p> </li> <li> <p>JVM 연결 고급 디버깅</p> </li> <li> <p>로깅의 성능 및 최적화</p> </li> </ul> </div> <div class="paragraph"> <p><em>이 글은 내 기술 블로그의 "Gradle 플러그인 개발" 시리즈의 일부입니다.</em></p> </div> </div> </div> https://cheroliv.com/blog/2025/0096_afficher-couleurs-asciidoc_post.html Sat, 1 Nov 2025 00:00:00 +0000 blog/2025/0096_afficher-couleurs-asciidoc_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_소개">소개</a></li> <li><a href="#_문제">문제</a> <ul class="sectlevel2"> <li><a href="#_사용_컨텍스트">사용 컨텍스트</a></li> <li><a href="#_가능한_접근_방법">가능한 접근 방법</a> <ul class="sectlevel3"> <li><a href="#_옵션_1_유니코드_문자">옵션 1: 유니코드 문자</a></li> <li><a href="#_옵션_2_외부_이미지">옵션 2 : 외부 이미지</a></li> <li><a href="#_옵션_3_사용자_정의_css_역할">옵션 3: 사용자 정의 CSS 역할</a></li> <li><a href="#_옵션_4_html_주입_선택된_솔루션">옵션 4 : HTML 주입 (선택된 솔루션)</a></li> </ul> </li> </ul> </li> <li><a href="#_해결책_를_사용한_html_인젝션">해결책: 를 사용한 HTML 인젝션</a> <ul class="sectlevel2"> <li><a href="#_작동_원리">작동 원리</a></li> <li><a href="#_구현">구현</a> <ul class="sectlevel3"> <li><a href="#_css_속성_설명">CSS 속성 설명</a></li> </ul> </li> <li><a href="#_완전한_예시">완전한 예시</a></li> </ul> </li> <li><a href="#_최적화_및_모범_사례">최적화 및 모범 사례</a> <ul class="sectlevel2"> <li><a href="#_밝은_색_관리">밝은 색 관리</a></li> <li><a href="#_정사각형_크기_조정">정사각형 크기 조정</a></li> <li><a href="#_변형_만들기">변형 만들기</a> <ul class="sectlevel3"> <li><a href="#_색_원">색 원</a></li> <li><a href="#_색_테두리가_있는_정사각형">색 테두리가 있는 정사각형</a></li> </ul> </li> </ul> </li> <li><a href="#_솔루션_아키텍처">솔루션 아키텍처</a></li> <li><a href="#_장점과_한계">장점과 한계</a> <ul class="sectlevel2"> <li><a href="#_장점">장점</a></li> <li><a href="#_제한">제한</a></li> <li><a href="#_접근성_개선">접근성 개선</a></li> </ul> </li> <li><a href="#_구체적인_예시_주제_문서">구체적인 예시: 주제 문서</a></li> <li><a href="#_결론">결론</a></li> <li><a href="#_자원">자원</a></li> </ul> </div> <div class="sect1"> <h2 id="_소개">소개</h2> <div class="sectionbody"> <div class="paragraph"> <p>기술 문서를 작성할 때, 특히 스타일 가이드나 사용자 인터페이스 사양을 작성할 때는 색상 팔레트를 표시해야 하는 경우가 자주 발생합니다. AsciiDoc은 문서 작성에 매우 강력하지만, 색상 샘플을 표시하기 위한 네이티브 구문을 제공하지 않습니다. 이 글에서는 이 문제를 살펴보고 HTML 삽입을 기반으로 한 우아한 솔루션을 제시합니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_문제">문제</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_사용_컨텍스트">사용 컨텍스트</h3> <div class="paragraph"> <p>상상해 보세요. 웹 애플리케이션 테마의 CSS 변수를 문서화하고 있습니다. 다음이 필요합니다:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>16진수 색상 코드 나열</p> </li> <li> <p>각 색상의 시각적 미리보기 표시</p> </li> <li> <p>소스 문서의 가독성 유지</p> </li> <li> <p>JBake와 같은 정적 사이트 생성기와 호환성을 보장해야 합니다.</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre>@startuml left to right direction skinparam packageStyle rectangle actor "기술 작가" as writer actor "독자" as reader rectangle "문서 AsciiDoc" { usecase "색상 팔레트 문서화" as UC1 usecase "16진수 코드 표시" as UC2 usecase "색상 시각화" as UC3 usecase "정적 사이트 생성" as UC4 usecase "문서 참조" as UC5 } writer --> UC1 UC1 ..> UC2 : include UC1 ..> UC3 : include UC1 --> UC4 UC4 --> UC5 UC5 <-- reader @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_가능한_접근_방법">가능한 접근 방법</h3> <div class="paragraph"> <p>여러 가지 해결책을 고려하여 AsciiDoc 문서에서 색상을 표시할 수 있습니다.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam componentStyle rectangle package "가능한 해결책" { component "유니코드 문자" as unicode component "외부 이미지" as images component "사용자 정의 CSS 역할" as css component "HTML 삽입" as html } package "평가 기준" { component "간결함" as simple component "휴대성" as portable component "맞춤 설정" as custom component "유지 보수" as maintain } unicode -down-> simple : ✓ unicode -down-> portable : ✓ unicode -down-> custom : ✗ images -down-> simple : ✗ images -down-> portable : ✗ images -down-> custom : ✓ css -down-> simple : ~ css -down-> portable : ✗ css -down-> custom : ✓ html -down-> simple : ✓ html -down-> portable : ✓ html -down-> custom : ✓✓ html -down-> maintain : ✓ note right of html Solution recommandée end note @enduml</pre> </div> </div> <div class="sect3"> <h4 id="_옵션_1_유니코드_문자">옵션 1: 유니코드 문자</h4> <div class="paragraph"> <p>유니코드 문자를 사용하는`■`(■)은 간단하지만 제한적입니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* ■ --accent-color: #7952b3 (violet Bootstrap)</code></pre> </div> </div> <div class="paragraph"> <p><strong>제한 사항</strong> : 색상을 제어할 수 없으며, 시스템 글꼴에 따라 달라집니다.</p> </div> </div> <div class="sect3"> <h4 id="_옵션_2_외부_이미지">옵션 2 : 외부 이미지</h4> <div class="paragraph"> <p>각 색상에 대해 PNG 또는 SVG 이미지를 생성합니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* image:colors/violet.svg[width=16] --accent-color: #7952b3</code></pre> </div> </div> <div class="paragraph"> <p><strong>제한점</strong> : 무거운 유지보수, 파일 증가, 자동 동기화 없음.</p> </div> </div> <div class="sect3"> <h4 id="_옵션_3_사용자_정의_css_역할">옵션 3: 사용자 정의 CSS 역할</h4> <div class="paragraph"> <p>CSS 클래스를 정의하고 AsciiDoc 역할을 통해 적용하기 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* [.color-violet]##■## --accent-color: #7952b3</code></pre> </div> </div> <div class="paragraph"> <p><strong>제한 사항</strong> : 외부 스타일 시트가 필요합니다, 모든 가능한 색상에 대한 사전 정의.</p> </div> </div> <div class="sect3"> <h4 id="_옵션_4_html_주입_선택된_솔루션">옵션 4 : HTML 주입 (선택된 솔루션)</h4> <div class="paragraph"> <p>매크로 사용``HTML을 인라인 스타일과 함께 삽입하기 위해 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* pass:[<span style="display:inline-block;width:1em;height:1em; background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: #7952b3 (violet Bootstrap)</code></pre> </div> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_해결책_를_사용한_html_인젝션">해결책: 를 사용한 HTML 인젝션</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_작동_원리">작동 원리</h3> <div class="paragraph"> <p>매크로``AsciiDoc는 해석되지 않은 원시 콘텐츠를 삽입할 수 있게 해줍니다. 이를 통해 인라인 CSS 스타일이 적용된 HTML을 직접 삽입할 수 있습니다.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml participant "문서 아스키독" as doc participant "프로세서\nAsciiDoc" as processor participant "pass:[] 매크로" as pass participant "HTML 최종" as html doc -> processor : Analyse document processor -> pass : Détecte pass:[] pass -> processor : Retourne HTML brut processor -> html : Insère sans transformation html -> html : Navigateur applique styles @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_구현">구현</h3> <div class="paragraph"> <p>다음은 주입할 HTML 구조입니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><span style="display:inline-block; width:1em; height:1em; background:#7952b3; vertical-align:middle; margin-right:0.5em"> </span></code></pre> </div> </div> <div class="sect3"> <h4 id="_css_속성_설명">CSS 속성 설명</h4> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 75%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">속성</th> <th class="tableblock halign-left valign-top">기능</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>display:inline-block</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">width/height를 설정할 수 있으며 인라인 흐름을 유지합니다</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>width:1em; height:1em</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">글꼴 크기 대비 정사각형 크기 (반응형)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>background:#7952b3</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">표시할 색상 (필요에 따라 변수)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>vertical-align:middle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">인접한 텍스트와 사각형을 정렬하세요</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>margin-right:0.5em</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">정사각형과 텍스트 사이의 간격</p></td> </tr> </tbody> </table> </div> </div> <div class="sect2"> <h3 id="_완전한_예시">완전한 예시</h3> <div class="paragraph"> <p>다음은 테마 팔레트를 문서화하는 예시입니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">== Thème Clair * pass:[<span style="display:inline-block;width:1em;height:1em;background:#f8f9fa;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#f8f9fa` (blanc cassé) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#212529` (noir très foncé) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#7952b3` (violet Bootstrap) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#61428f;vertical-align:middle;margin-right:0.5em"></span>] --accent-hover: `#61428f` (violet plus foncé) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --card-bg: `#ffffff` (blanc)</code></pre> </div> </div> <div class="paragraph"> <p>다음 렌더링을 생성하는 :</p> </div> <div class="paragraph"> <p><strong>라이트 테마</strong></p> </div> <div class="ulist"> <ul> <li> <p>통과:[<span style="display:inline-block;width:1em;height:1em;background:#f8f9fa;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary:`#f8f9fa`(아이보리)</p> </li> <li> <p><span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span> --text-primary:`#212529`(매우 진한 검정)</p> </li> <li> <p><span style="display:inline-block;width:1em;height:1em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span> --accent-color:`#7952b3`(보라색 Bootstrap)</p> </li> <li> <p><span style="display:inline-block;width:1em;height:1em;background:#61428f;vertical-align:middle;margin-right:0.5em"></span> --accent-hover:`#61428f`(더 어두운 보라색)</p> </li> <li> <p><span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span> --card-bg:`#ffffff`(흰)</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_최적화_및_모범_사례">최적화 및 모범 사례</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_밝은_색_관리">밝은 색 관리</h3> <div class="paragraph"> <p>매우 밝은 색 (흰색, 매우 밝은 회색)의 경우 흰색 배경에서 보이도록 테두리를 추가하세요:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><span style="display:inline-block;width:1em;height:1em; background:#ffffff;border:1px solid #ccc; vertical-align:middle;margin-right:0.5em"></span></code></pre> </div> </div> <div class="paragraph"> <p>회색 테두리 (<code>border:1px solid #ccc</code>) 흰색 배경 위의 흰색 사각형의 경계를 지정할 수 있다.</p> </div> </div> <div class="sect2"> <h3 id="_정사각형_크기_조정">정사각형 크기 조정</h3> <div class="paragraph"> <p>필요에 따라 사각형의 크기를 조정할 수 있습니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* pass:[<span style="display:inline-block;width:1.5em;height:1.5em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] Grand carré * pass:[<span style="display:inline-block;width:0.8em;height:0.8em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] Petit carré</code></pre> </div> </div> <div class="paragraph"> <p>단위 사용`em`사각형이 글꼴 크기에 맞게 조정됨을 보장합니다.</p> </div> </div> <div class="sect2"> <h3 id="_변형_만들기">변형 만들기</h3> <div class="paragraph"> <p>특정 요구 사항을 위해 다양한 형태를 만들 수 있습니다:</p> </div> <div class="sect3"> <h4 id="_색_원">색 원</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;border-radius:50%;vertical-align:middle;margin-right:0.5em"></span>] Cercle violet</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_색_테두리가_있는_정사각형">색 테두리가 있는 정사각형</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:3px solid #7952b3;vertical-align:middle;margin-right:0.5em"></span>] Bordure violette</code></pre> </div> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_솔루션_아키텍처">솔루션 아키텍처</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>@startuml package "문서 워크플로우" { [Document AsciiDoc\navec pass macro] as asciidoc [Processeur JBake] as jbake [Site HTML statique] as html [Navigateur Web] as browser } asciidoc --> jbake : 1. Compilation jbake --> html : 2. Génération html --> browser : 3. Affichage browser --> browser : 4. Rendu CSS note right of asciidoc Contient les balises pass:[] avec HTML inline end note note right of jbake Préserve le HTML dans pass:[] end note note right of browser Applique les styles inline CSS end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_장점과_한계">장점과 한계</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_장점">장점</h3> <div class="ulist"> <ul> <li> <p>✓ <strong>자율성</strong> : 외부 파일에 대한 의존 없음</p> </li> <li> <p>✓ <strong>이식성</strong> : 모든 AsciiDoc 프로세서와 작동합니다</p> </li> <li> <p>✓ <strong>동기화</strong> : 색상 코드는 HTML에 직접 있습니다.</p> </li> <li> <p>✓ <strong>유연성</strong> : 스타일의 완전한 커스터마이징</p> </li> <li> <p>✓ <strong>Maintenance</strong> : 간단한 16진수 코드 수정</p> </li> <li> <p>✓ <strong>호환성 JBake</strong> : 정적 사이트 생성기와 완벽하게 호환됩니다</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_제한">제한</h3> <div class="ulist"> <ul> <li> <p>✗ <strong>장황함</strong> : 반복적인 HTML 코드가 AsciiDoc 소스에 있습니다.</p> </li> <li> <p>✗ <strong>소스 가독성</strong> : 소스 문서가 덜 깔끔합니다.</p> </li> <li> <p>✗ <strong>접근성</strong> : 네이티브 대체 텍스트가 없습니다(수동으로 추가해야 함)</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_접근성_개선">접근성 개선</h3> <div class="paragraph"> <p>스크린 리더가 사각형에 접근할 수 있게 만들려면 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* pass:[<span role="img" aria-label="Couleur violet Bootstrap" style="display:inline-block;width:1em;height:1em;background:#7952b3; vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#7952b3` (violet Bootstrap)</code></pre> </div> </div> <div class="paragraph"> <p>속성들`role="img"` et `aria-label`이들은 보조 기술이 시각적 콘텐츠를 이해하고 설명하도록 허용한다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_구체적인_예시_주제_문서">구체적인 예시: 주제 문서</h2> <div class="sectionbody"> <div class="paragraph"> <p>다음은 여러 주제를 문서화한 완전한 예시입니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Guide des couleurs de l'application == Thème Clair (`:root`) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#f8f9fa;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#f8f9fa` (blanc cassé) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#212529` (noir très foncé) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#7952b3` (violet Bootstrap) == Thème Sombre (`[data-bs-theme="dark"]`) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#212529` (noir très foncé) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #999;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#ffffff` (blanc) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#0d6efd;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#0d6efd` (bleu Bootstrap) == Thème Contraste Élevé (`[data-bs-theme="high-contrast"]`) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#000000;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#000000` (noir) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #000;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#ffffff` (blanc) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#00ff00;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#00ff00` (vert vif)</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_결론">결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>매크로를 통한 HTML 삽입``AsciiDoc은 기술 문서에 색상 샘플을 표시하는 우아하고 실용적인 솔루션을 제공합니다. 약간 장황할 수 있지만, 이 접근 방식은 최대 이식성을 보장하고 유지 관리를 간소화합니다.</p> </div> <div class="paragraph"> <p>이 기술은 외부 구성이 필요 없으며, 추가 스타일시트도 필요하지 않으며, JBake 및 모든 표준 AsciiDoc 프로세서와 즉시 작동합니다.</p> </div> <div class="paragraph"> <p>첫 번째 색이 있는 사각형을 만든 뒤에는, HTML 코드를 복사해서 붙여넣고 16진수 코드를 변경하면 빠르게 전체 팔레트를 만들 수 있습니다.</p> </div> <div class="paragraph"> <p>이 기술은 맞춤형 시각적 렌더링이 필요한 다른 사용 사례로 확장될 수 있습니다: 아이콘, 배지, 간단한 그래프, 또는 스타일을 정확히 제어해야 하는 모든 시각적 요소.</p> </div> </div> </div> <div class="sect1"> <h2 id="_자원">자원</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://docs.asciidoctor.org/asciidoc/latest/pass/pass-macro/" target="_blank" rel="noopener">문서 AsciiDoc : pass macro</a></p> </li> <li> <p><a href="https://jbake.org/docs/2.6.7/" target="_blank" rel="noopener">JBake 문서</a></p> </li> <li> <p><a href="https://developer.mozilla.org/fr/docs/Web/CSS/color_value" target="_blank" rel="noopener">MDN : CSS 색상 값</a></p> </li> </ul> </div> <div class="paragraph"> <p><em>2025-11-01에 게시된 기사</em></p> </div> </div> </div> https://cheroliv.com/blog/2025/0095_i18n-site-statique-jbake-thymeleaf_post.html Mon, 20 Oct 2025 00:00:00 +0000 blog/2025/0095_i18n-site-statique-jbake-thymeleaf_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_소개">소개</a> <ul class="sectlevel2"> <li><a href="#_사용_사례_다이어그램_use_case">사용 사례 다이어그램 (Use Case)</a></li> </ul> </li> <li><a href="#_국제화_아키텍처">국제화 아키텍처</a> <ul class="sectlevel2"> <li><a href="#_구조도_파일_조직">구조도 (파일 조직)</a></li> <li><a href="#_왜_이_접근_방식인가요">왜 이 접근 방식인가요?</a></li> <li><a href="#_컴포넌트_다이어그램">컴포넌트 다이어그램</a></li> </ul> </li> <li><a href="#_thymeleaf을_사용한_템플릿의_국제화">Thymeleaf을 사용한 템플릿의 국제화</a> <ul class="sectlevel2"> <li><a href="#_메시지_파일의_구조">메시지 파일의 구조</a></li> <li><a href="#_메시지_파일의_내용">메시지 파일의 내용</a></li> <li><a href="#_템플릿에서의_사용">템플릿에서의 사용</a></li> <li><a href="#_시퀀스_다이어그램_i18n_해상도">시퀀스 다이어그램 - i18n 해상도</a></li> <li><a href="#_jbake의_로케일_구성">JBake의 로케일 구성</a></li> </ul> </li> <li><a href="#_문서의_i18n_폴더별_구성">문서의 I18n : 폴더별 구성</a> <ul class="sectlevel2"> <li><a href="#_흐름도flow_생성">흐름도(Flow) - 생성</a></li> <li><a href="#_폴더_구조">폴더 구조</a></li> <li><a href="#_이_접근_방식의_장점">이 접근 방식의 장점</a></li> <li><a href="#_기사의_메타데이터">기사의 메타데이터</a></li> <li><a href="#_url_설정">URL 설정</a></li> </ul> </li> <li><a href="#_멀티언어_표시용_템플릿">멀티언어 표시용 템플릿</a> <ul class="sectlevel2"> <li><a href="#_언어_선택기가_있는_기사_템플릿">언어 선택기가 있는 기사 템플릿</a></li> <li><a href="#_언어별_필터링된_인덱스">언어별 필터링된 인덱스</a></li> </ul> </li> <li><a href="#_언어_간_내비게이션">언어 간 내비게이션</a> <ul class="sectlevel2"> <li><a href="#_글로벌_언어_선택기">글로벌 언어 선택기</a></li> <li><a href="#_흐름도_사용자_보기">흐름도 - 사용자 보기</a></li> <li><a href="#_선택자에_대한_css_스타일">선택자에 대한 CSS 스타일</a></li> </ul> </li> <li><a href="#_언어별_rss_피드">언어별 RSS 피드</a></li> <li><a href="#_좋은_관행과_팁">좋은 관행과 팁</a> <ul class="sectlevel2"> <li><a href="#_1_기사_식별자의_일관성">1. 기사 식별자의 일관성</a></li> <li><a href="#_2_일관된_날짜">2. 일관된 날짜</a></li> <li><a href="#_3_다국어_태그">3. 다국어 태그</a></li> <li><a href="#_4_미번역된_기사_관리">4. 미번역된 기사 관리</a></li> <li><a href="#_5_다국어_사이트맵">5. 다국어 사이트맵</a></li> </ul> </li> <li><a href="#_결론">결론</a> <ul class="sectlevel2"> <li><a href="#_배포도">배포도</a></li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_소개">소개</h2> <div class="sectionbody"> <div class="paragraph"> <p>정적 웹사이트의 국제화(i18n)는 처음엔 복잡해 보일 수 있지만, JBake와 Thymeleaf를 결합하면 다국어 사이트를 구축하기 위한 우아한 솔루션을 제공합니다. 이 글에서는 블로그에 i18n을 어떻게 구현했는지 보여드리겠습니다. 이때 템플릿과 다국어 게시글 관리를 모두 다룰 것입니다.</p> </div> <div class="sect2"> <h3 id="_사용_사례_다이어그램_use_case">사용 사례 다이어그램 (Use Case)</h3> <div class="listingblock"> <div class="content"> <pre>@startuml left to right direction skinparam packageStyle rectangle actor "작가" as author actor "프랑스어 리더" as reader_fr actor "플레이어 EN" as reader_en rectangle "다언어 JBake 사이트" { usecase "FR 기사 작성" as UC1 usecase "기사 쓰기 EN" as UC2 usecase "i18n 메시지 구성" as UC3 usecase "사이트 생성" as UC4 usecase "FR 기사 읽기" as UC5 usecase "기사 읽기 EN" as UC6 usecase "언어 변경" as UC7 usecase "사용 가능한 번역 보기" as UC8 } author --> UC1 author --> UC2 author --> UC3 author --> UC4 reader_fr --> UC5 reader_fr --> UC7 reader_fr --> UC8 reader_en --> UC6 reader_en --> UC7 reader_en --> UC8 UC1 ..> UC4 : <<include>> UC2 ..> UC4 : <<include>> UC3 ..> UC4 : <<include>> UC5 ..> UC8 : <<extend>> UC6 ..> UC8 : <<extend>> @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_국제화_아키텍처">국제화 아키텍처</h2> <div class="sectionbody"> <div class="paragraph"> <p>우리 접근 방식은 두 가지 기둥을 기반으로 합니다.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>템플릿의 i18n</strong>: 인터페이스 요소에 대한 Thymeleaf 메시지 파일 사용</p> </li> <li> <p><strong>콘텐츠의 국제화</strong>: 언어별로 기사들을 전용 폴더 구조에 정리</p> </li> </ol> </div> <div class="sect2"> <h3 id="_구조도_파일_조직">구조도 (파일 조직)</h3> <div class="listingblock"> <div class="content"> <pre>@startuml @startsalt { {T + projet-jbake ++ content +++ blog ++++ 2024 +++++ fr ++++++ article1.adoc ++++++ article2.adoc +++++ en ++++++ article1.adoc ++++++ article2.adoc ++++ 2025 +++++ fr ++++++ guide-i18n.adoc +++++ en ++++++ i18n-guide.adoc ++ templates +++ post.html +++ index.html +++ index_en.html +++ messages.properties +++ messages_fr.properties +++ messages_en.properties ++ assets +++ css +++ js +++ img ++ jbake.properties ++ output +++ fr ++++ blog +++++ 2025 ++++++ guide-i18n.html +++ en ++++ blog +++++ 2025 ++++++ i18n-guide.html } } @endsalt @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_왜_이_접근_방식인가요">왜 이 접근 방식인가요?</h3> <div class="paragraph"> <p>이 분할을 통해:</p> </div> <div class="ulist"> <ul> <li> <p>어떤 언어든 인터페이스의 일관성을 유지하라</p> </li> <li> <p>컨텐츠와 기사 번역을 독립적으로 관리</p> </li> <li> <p>주요 리팩터링 없이 새 언어 추가를 용이하게 하다</p> </li> <li> <p>특정 언어에서만 이용 가능한 항목을 허용하다</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_컴포넌트_다이어그램">컴포넌트 다이어그램</h3> <div class="listingblock"> <div class="content"> <pre>@startuml skinparam componentStyle rectangle package "소스" { folder "content/blog/2025/" { folder "fr/" as content_fr { [article1.adoc] [article2.adoc] } folder "영어/" as content_en { [article1.adoc] as article1_en [article2.adoc] as article2_en } } folder "템플릿/" { [post.html] [index.html] [index_en.html] } folder "(empty)" { [messages_fr.properties] [messages_en.properties] } [jbake.properties] } package "JBake Engine" { [Parser AsciiDoc] as parser [Template Engine\nThymeleaf] as thymeleaf [Generator] as generator [I18n Resolver] as i18n } package "생성된 사이트" { folder "fr/" { folder "blog/2025/" as blog_fr { [article1.html] [article2.html] } } folder "영어/" { folder "blog/2025/" as blog_en { [article1.html] as article1_html_en [article2.html] as article2_html_en } } } content_fr --> parser content_en --> parser parser --> generator templates --> thymeleaf messages --> i18n i18n --> thymeleaf thymeleaf --> generator jbake.properties --> generator generator --> blog_fr generator --> blog_en @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_thymeleaf을_사용한_템플릿의_국제화">Thymeleaf을 사용한 템플릿의 국제화</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_메시지_파일의_구조">메시지 파일의 구조</h3> <div class="paragraph"> <p>첫 번째 단계는 지원되는 각 언어에 대한 속성 파일을 만드는 것입니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">src/jbake/templates/ ├── messages.properties # Fallback par défaut ├── messages_fr.properties # Français ├── messages_en.properties # Anglais └── messages_de.properties # Allemand</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_메시지_파일의_내용">메시지 파일의 내용</h3> <div class="paragraph"> <p>다음은 파일 예시입니다.<code>messages_fr.properties</code>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties"># Navigation nav.home=Accueil nav.blog=Blog nav.about=À propos nav.contact=Contact # Articles article.readmore=Lire la suite article.published=Publié le article.tags=Étiquettes article.also.available=Également disponible en # Interface site.title=Mon Blog Technique site.description=Partage de connaissances et expériences footer.copyright=© 2025 Tous droits réservés search.placeholder=Rechercher un article...</code></pre> </div> </div> <div class="paragraph"> <p>그리고 그 영어 판`messages_en.properties`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties"># Navigation nav.home=Home nav.blog=Blog nav.about=About nav.contact=Contact # Articles article.readmore=Read more article.published=Published on article.tags=Tags article.also.available=Also available in # Interface site.title=My Tech Blog site.description=Sharing knowledge and experiences footer.copyright=© 2025 All rights reserved search.placeholder=Search articles...</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_템플릿에서의_사용">템플릿에서의 사용</h3> <div class="paragraph"> <p>Thymeleaf 템플릿에서 구문을 사용하세요`#{}`메시지에 접근하려면 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html xmlns:th="http://www.thymeleaf.org"> <head> <title th:text="#{site.title}">Mon Blog</title> <meta name="description" th:content="#{site.description}" /> </head> <body> <nav> <a th:href="@{/}" th:text="#{nav.home}">Accueil</a> <a th:href="@{/blog/}" th:text="#{nav.blog}">Blog</a> <a th:href="@{/about.html}" th:text="#{nav.about}">À propos</a> </nav> <footer> <p th:text="#{footer.copyright}">Copyright</p> </footer> </body> </html></code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_시퀀스_다이어그램_i18n_해상도">시퀀스 다이어그램 - i18n 해상도</h3> <div class="listingblock"> <div class="content"> <pre>@startuml actor Auteur participant JBake participant "AsciiDoc 파서" as parser participant "타임리프 엔진" as thymeleaf participant "I18n 해결사" as i18n database "messages_*.properties" as messages Auteur -> JBake: jbake -b activate JBake JBake -> parser: Lire article.fr.adoc activate parser parser --> JBake: Contenu + métadonnées\n(lang=fr, article-id=xyz) deactivate parser JBake -> parser: Lire article.en.adoc activate parser parser --> JBake: Contenu + métadonnées\n(lang=en, article-id=xyz) deactivate parser JBake -> thymeleaf: Générer page FR activate thymeleaf thymeleaf -> i18n: Résoudre #{nav.home} activate i18n i18n -> messages: Lire messages_fr.properties messages --> i18n: "홈" i18n --> thymeleaf: "홈" deactivate i18n thymeleaf -> JBake: Rechercher traductions\n(article-id=xyz, lang!=fr) JBake --> thymeleaf: article.en.html trouvé thymeleaf --> JBake: /fr/blog/article.html deactivate thymeleaf JBake -> thymeleaf: Générer page EN activate thymeleaf thymeleaf -> i18n: Résoudre #{nav.home} activate i18n i18n -> messages: Lire messages_en.properties messages --> i18n: "집" i18n --> thymeleaf: "집" deactivate i18n thymeleaf -> JBake: Rechercher traductions\n(article-id=xyz, lang!=en) JBake --> thymeleaf: article.fr.html trouvé thymeleaf --> JBake: /en/blog/article.html deactivate thymeleaf JBake --> Auteur: Site généré deactivate JBake @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_jbake의_로케일_구성">JBake의 로케일 구성</h3> <div class="paragraph"> <p>당신의 파일에서`jbake.properties`, 기본 로켈을 설정하세요 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties"># Locale par défaut thymeleaf.locale=fr # Encodage template.encoding=UTF-8</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_문서의_i18n_폴더별_구성">문서의 I18n : 폴더별 구성</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_흐름도flow_생성">흐름도(Flow) - 생성</h3> <div class="listingblock"> <div class="content"> <pre>@startuml start :Lire jbake.properties; :Charger configuration i18n; partition "각 AsciiDoc 파일에 대해" { :Lire métadonnées\n(:jbake-lang:, :jbake-article-id:); :Parser contenu AsciiDoc; :Stocker en mémoire avec langue; } partition "각 템플릿마다" { :Charger template Thymeleaf; :Identifier langue cible; :Charger messages_{lang}.properties; partition "콘텐츠 필터링" { :Filtrer articles par langue; :Grouper traductions\npar article-id; } :Appliquer template avec i18n; :Générer HTML dans /{lang}/; } :Copier assets statiques; :Générer sitemap multilingue; :Générer flux RSS par langue; stop @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_폴더_구조">폴더 구조</h3> <div class="paragraph"> <p>파일 이름에 접미사를 사용하는 대신, 더 명확하고 유지보수가 쉬운 폴더 기반 조직을 선택했습니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">content/blog/ ├── 2024/ │ ├── fr/ │ │ ├── introduction-jbake.adoc │ │ ├── guide-thymeleaf.adoc │ │ └── astuces-asciidoc.adoc │ └── en/ │ ├── introduction-jbake.adoc │ ├── thymeleaf-guide.adoc │ └── asciidoc-tips.adoc └── 2025/ ├── fr/ │ └── internationalisation-jbake.adoc └── en/ └── jbake-internationalization.adoc</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_이_접근_방식의_장점">이 접근 방식의 장점</h3> <div class="paragraph"> <p>이 구조는 여러 가지 장점이 있습니다:</p> </div> <div class="ulist"> <ul> <li> <p><strong>명확한 분리</strong>: 각 언어마다 고유한 공간이 있다</p> </li> <li> <p><strong>유연한 이름 지정</strong>: 파일이 언어에 따라 다른 이름을 가질 수 있다</p> </li> <li> <p><strong>확장성</strong>: 새로운 언어를 추가하기 쉽다</p> </li> <li> <p><strong>자연 조직</strong>: JBake의 시간적 논리를 따릅니다</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_기사의_메타데이터">기사의 메타데이터</h3> <div class="paragraph"> <p>각 문서는 번역 간 연결을 허용하기 위해 메타데이터를 포함해야 합니다. 다음은 예시 :</p> </div> <div class="paragraph"> <p><strong>프랑스어 버전</strong></think> (No content to translate)<code>2025/fr/internationalisation-jbake.adoc</code>) :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Internationalisation d'un site statique JBake :jbake-type: post :jbake-status: published :jbake-date: 2025-10-20 :jbake-lang: fr :jbake-article-id: jbake-i18n-thymeleaf :jbake-tags: jbake, thymeleaf, i18n :jbake-description: Guide pour mettre en place l'i18n avec JBake</code></pre> </div> </div> <div class="paragraph"> <p><strong>영어 버전</strong>(<code>2025/en/jbake-internationalization.adoc</code>) :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Internationalizing a JBake Static Site :jbake-type: post :jbake-status: published :jbake-date: 2025-10-20 :jbake-lang: en :jbake-article-id: jbake-i18n-thymeleaf :jbake-tags: jbake, thymeleaf, i18n :jbake-description: Guide to implement i18n with JBake</code></pre> </div> </div> <div class="paragraph"> <p>속성`:jbake-article-id:`중요합니다 : 같은 기사의 다양한 번역들을 연결할 수 있게 해줍니다.</p> </div> </div> <div class="sect2"> <h3 id="_url_설정">URL 설정</h3> <div class="paragraph"> <p>에`jbake.properties`, URL 패턴을 언어를 포함하도록 구성하세요 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties"># Pattern d'URL avec langue post.permalink.pattern=:lang/blog/:year/:name.html # Langue par défaut site.default.lang=fr</code></pre> </div> </div> <div class="paragraph"> <p>이는 다음과 같은 URL을 생성합니다:</p> </div> <div class="ulist"> <ul> <li> <p><code>/fr/blog/2025/internationalisation-jbake.html</code></p> </li> <li> <p><code>/en/blog/2025/jbake-internationalization.html</code></p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_멀티언어_표시용_템플릿">멀티언어 표시용 템플릿</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_언어_선택기가_있는_기사_템플릿">언어 선택기가 있는 기사 템플릿</h3> <div class="paragraph"> <p>템플릿을 만드세요`post.html`사용 가능한 번역을 표시합니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html xmlns:th="http://www.thymeleaf.org"> <head> <title th:text="${content.title}">Article</title> </head> <body> <article> <header> <h1 th:text="${content.title}">Titre</h1> <div class="article-meta"> <time th:text="${#dates.format(content.date, 'dd MMMM yyyy')}" th:attr="datetime=${#dates.format(content.date, 'yyyy-MM-dd')}"> Date </time> <!-- Sélecteur de traductions --> <div class="translations" th:if="${content['article-id']}"> <span th:text="#{article.also.available}">Aussi disponible en :</span> <ul class="language-list"> <li th:each="post : ${published_posts}" th:if="${post['article-id'] == content['article-id'] and post.lang != content.lang}"> <a th:href="${post.uri}" th:text="${post.lang.toUpperCase()}"> LANG </a> </li> </ul> </div> </div> </header> <div class="content" th:utext="${content.body}"> Contenu de l'article </div> <footer class="article-footer"> <div class="tags" th:if="${content.tags}"> <span th:text="#{article.tags}">Étiquettes :</span> <span th:each="tag : ${content.tags}"> <a th:href="@{/tags/{tag}.html(tag=${tag})}" th:text="${tag}">tag</a> </span> </div> </footer> </article> </body> </html></code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_언어별_필터링된_인덱스">언어별 필터링된 인덱스</h3> <div class="paragraph"> <p>각 언어에 대한 인덱스 템플릿을 만드세요 :</p> </div> <div class="paragraph"> <p><strong>index.html</strong>(프랑스어 색인) :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html xmlns:th="http://www.thymeleaf.org"> <head> <title th:text="#{site.title}">Mon Blog</title> </head> <body> <main> <h1 th:text="#{nav.blog}">Blog</h1> <div class="articles-list"> <article th:each="post : ${published_posts}" th:if="${post.lang == 'fr'}"> <h2> <a th:href="${post.uri}" th:text="${post.title}">Titre</a> </h2> <time th:text="${#dates.format(post.date, 'dd MMMM yyyy')}"> Date </time> <p th:text="${post.description}">Description</p> <a th:href="${post.uri}" th:text="#{article.readmore}"> Lire la suite </a> </article> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><strong>index_en.html</strong>(영어 색인) :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html xmlns:th="http://www.thymeleaf.org"> <head> <title th:text="#{site.title}">My Blog</title> </head> <body> <main> <h1 th:text="#{nav.blog}">Blog</h1> <div class="articles-list"> <article th:each="post : ${published_posts}" th:if="${post.lang == 'en'}"> <h2> <a th:href="${post.uri}" th:text="${post.title}">Title</a> </h2> <time th:text="${#dates.format(post.date, 'dd MMMM yyyy')}"> Date </time> <p th:text="${post.description}">Description</p> <a th:href="${post.uri}" th:text="#{article.readmore}"> Read more </a> </article> </div> </main> </body> </html></code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_언어_간_내비게이션">언어 간 내비게이션</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_글로벌_언어_선택기">글로벌 언어 선택기</h3> </div> <div class="sect2"> <h3 id="_흐름도_사용자_보기">흐름도 - 사용자 보기</h3> <div class="listingblock"> <div class="content"> <pre>@startuml start :Utilisateur accède au site; if (Langue préférée ?) then (FR) :Afficher /index.html; :Lister articles FR; else (EN) :Afficher /en/index.html; :Lister articles EN; endif :Utilisateur clique sur article; :Afficher article\navec métadonnées; if (Traductions disponibles ?) then (oui) :Afficher sélecteur\nde traductions; if (Changement de langue ?) then (oui) :Rediriger vers\ntraduction; :Afficher article\ndans nouvelle langue; else (non) :Continuer lecture; endif else (non) :Continuer lecture; endif stop @enduml</pre> </div> </div> <div class="paragraph"> <p>메인 템플릿에 언어 선택기를 추가하세요:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><nav class="language-switcher"> <a href="/index.html" th:classappend="${content.lang == 'fr'} ? 'active'" title="Français"> 🇫🇷 FR </a> <a href="/en/index.html" th:classappend="${content.lang == 'en'} ? 'active'" title="English"> 🇬🇧 EN </a> </nav></code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_선택자에_대한_css_스타일">선택자에 대한 CSS 스타일</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">.language-switcher { display: flex; gap: 1rem; padding: 0.5rem; background: #f5f5f5; border-radius: 4px; } .language-switcher a { padding: 0.5rem 1rem; text-decoration: none; color: #333; border-radius: 4px; transition: background 0.2s; } .language-switcher a:hover { background: #e0e0e0; } .language-switcher a.active { background: #007bff; color: white; } .translations { margin: 1rem 0; padding: 1rem; background: #f8f9fa; border-left: 4px solid #007bff; } .language-list { display: inline-flex; gap: 0.5rem; list-style: none; padding: 0; margin: 0; } .language-list li::after { content: "•"; margin-left: 0.5rem; } .language-list li:last-child::after { content: ""; }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_언어별_rss_피드">언어별 RSS 피드</h2> <div class="sectionbody"> <div class="paragraph"> <p>언어별로 분리된 RSS 피드를 만들려면 별도의 템플릿을 만들어야 합니다 :</p> </div> <div class="paragraph"> <p><strong>feed.xml</strong>(프랑스어 흐름) :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><?xml version="1.0" encoding="UTF-8"?> <rss version="2.0" xmlns:th="http://www.thymeleaf.org"> <channel> <title th:text="#{site.title}">Mon Blog</title> <link th:text="${config.site_host}">http://example.com</link> <description th:text="#{site.description}">Description</description> <language>fr</language> <item th:each="post : ${published_posts}" th:if="${post.lang == 'fr'}"> <title th:text="${post.title}">Titre</title> <link th:text="${config.site_host + post.uri}">Lien</link> <pubDate th:text="${#dates.format(post.date, 'EEE, dd MMM yyyy HH:mm:ss Z')}"> Date </pubDate> <description th:text="${post.description}">Description</description> </item> </channel> </rss></code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_좋은_관행과_팁">좋은 관행과 팁</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_1_기사_식별자의_일관성">1. 기사 식별자의 일관성</h3> <div class="paragraph"> <p>확인해 주세요`:jbake-article-id:`는 같은 기사의 모든 번역에 대해 동일합니다. 일관된 형식을 사용하세요:</p> </div> <div class="ulist"> <ul> <li> <p>영문 식별자를 선호하여 범용성을 높이세요</p> </li> <li> <p>단어를 구분하기 위해 하이픈을 사용하세요.</p> </li> <li> <p>특수 문자를 피하세요</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_2_일관된_날짜">2. 일관된 날짜</h3> <div class="paragraph"> <p>기사의 모든 번역은 동일한 출판일을 가져야 합니다 (<code>:jbake-date:</code>). 이를 통해 정렬과 연대순 표시가 쉬워집니다.</p> </div> </div> <div class="sect2"> <h3 id="_3_다국어_태그">3. 다국어 태그</h3> <div class="paragraph"> <p>태그에 대해서는 두 가지 옵션이 있습니다 :</p> </div> <div class="paragraph"> <p><strong>옵션 1: 영어 보편적 태그</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">:jbake-tags: java, spring-boot, microservices</code></pre> </div> </div> <div class="paragraph"> <p><strong>옵션 2: 매핑을 사용한 번역된 태그</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc"># Version française :jbake-tags: java, spring-boot, microservices # Version anglaise :jbake-tags: java, spring-boot, microservices</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_4_미번역된_기사_관리">4. 미번역된 기사 관리</h3> <div class="paragraph"> <p>모든 문서를 번역할 의무는 없습니다. 한 언어로만 존재하는 문서는 다른 언어의 목록에 단순히 표시되지 않을 것입니다.</p> </div> </div> <div class="sect2"> <h3 id="_5_다국어_사이트맵">5. 다국어 사이트맵</h3> <div class="paragraph"> <p>모든 언어를 포함하는 사이트맵을 생성하세요 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><?xml version="1.0" encoding="UTF-8"?> <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:th="http://www.thymeleaf.org"> <url th:each="post : ${published_posts}"> <loc th:text="${config.site_host + post.uri}">URL</loc> <lastmod th:text="${#dates.format(post.date, 'yyyy-MM-dd')}">Date</lastmod> <!-- Liens alternatifs pour les traductions --> <xhtml:link th:each="translation : ${published_posts}" th:if="${translation['article-id'] == post['article-id'] and translation.lang != post.lang}" rel="alternate" th:attr="hreflang=${translation.lang},href=${config.site_host + translation.uri}" /> </url> </urlset></code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_결론">결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>JBake 사이트를 Thymeleaf과 함께 국제화하는 것은 강력한 유지 관리 가능한 접근 방식입니다. 메시지 파일을 통해 템플릿의 i18n을 분리하고 폴더 조직을 통해 콘텐츠의 i18n을 분리함으로써, 쉽게 발전할 수 있는 유연한 시스템을 얻을 수 있습니다.</p> </div> <div class="paragraph"> <p>기억해야 할 핵심 사항:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Thymeleaf 메시지 파일</strong>사용자 인터페이스를 위해</p> </li> <li> <p><strong>폴더별 조직</strong>(연도/언어) 기사용</p> </li> <li> <p><strong>아이템 식별자</strong>번역들을 연결하기 위해</p> </li> <li> <p><strong>전용 템플릿</strong>각 언어마다</p> </li> <li> <p><strong>명시적 URL</strong>언어 코드를 포함하여</p> </li> </ul> </div> <div class="sect2"> <h3 id="_배포도">배포도</h3> <div class="listingblock"> <div class="content"> <pre>@startuml node "개발 기계" { artifact "출처" { folder "만족한" folder "템플릿/" folder "자산/" } component "JBake CLI" as jbake Sources --> jbake : jbake -b } node "빌드 서버 (CI/CD)" { component "GitHub Actions 또는 GitLab CI" as ci jbake --> ci : push } cloud "CDN / 호스팅" { node "정적 웹 서버" { artifact "생성된 사이트" { folder "/ko/blog/" folder "/en/blog/" folder "/assets/" } } } ci --> "생성된 사이트" : déploiement actor "독자들" as users users --> "정적 웹 서버" : HTTPS @enduml</pre> </div> </div> <div class="paragraph"> <p>이 아키텍처를 사용하면 두 언어로 시작하기가 간편하고 추가 언어를 추가할 수 있으며 큰 리팩터링이 필요하지 않습니다. 모든 것이 완전히 정적이며 고성능을 유지하며 JBake 철학을 따릅니다.</p> </div> <div class="paragraph"> <p>다국어 개발 잘하세요! 🌍</p> </div> </div> </div> </div> https://cheroliv.com/blog/2025/0094_tor_browser_install_post.html Sun, 5 Oct 2025 00:00:00 +0000 blog/2025/0094_tor_browser_install_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_소개">소개</a></li> <li><a href="#_tor_및_해당_서명_다운로드">Tor 및 해당 서명 다운로드</a></li> <li><a href="#_서명의_암호학적_검증">서명의 암호학적 검증</a> <ul class="sectlevel2"> <li><a href="#_1_tor_project의_공개_키_가져오기">1. Tor Project의 공개 키 가져오기</a></li> <li><a href="#_2_서명_확인">2. 서명 확인</a></li> <li><a href="#_실제_사례_유효한_서명이지만_인증되지_않은_키">실제 사례 : 유효한 서명이지만 인증되지 않은 키</a></li> </ul> </li> <li><a href="#_왜_서명을_검증해야_하나요">왜 서명을 검증해야 하나요?</a></li> <li><a href="#_토르_브라우저_추출_및_실행">토르 브라우저 추출 및 실행</a></li> <li><a href="#_우분투_데스크톱_통합">우분투 데스크톱 통합</a></li> <li><a href="#_tor를_이용해_교육_자료_탐색하기">Tor를 이용해 교육 자료 탐색하기</a></li> <li><a href="#_tor_browser_업데이트">Tor Browser 업데이트</a></li> <li><a href="#_결론">결론</a></li> <li><a href="#_참고문헌">참고문헌</a></li> </ul> </div> <div class="sect1"> <h2 id="_소개">소개</h2> <div class="sectionbody"> <div class="paragraph"> <p>디지털 프라이버시가 점점 더 위협받는 세상에서, *Tor Browser*는 익명성을 유지하고 정보의 자유를 보호하는 데 필수적인 도구로 남아 있다. 그러나 다운로드한 소프트웨어를 실행하지 않지 않도록 하는 것이 중요하다.<strong>그의 진위를 확인했다</strong>. 이 글은 다음과 같은 완전한 방법을 제시합니다:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>다운로드 <strong>Tor Browser</strong> 및 그 서명`.asc`</p> </li> <li> <p>다운로드된 파일의 유효성을 확인하십시오</p> </li> <li> <p>Ubuntu에서 <strong>Tor Browser</strong> 설치 및 실행</p> </li> <li> <p>데스크톱 메뉴에 추가하여 일상적으로 사용하기</p> </li> <li> <p>Tor를 통해 교육 자료와 윤리적 OSINT를 탐색하다</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_tor_및_해당_서명_다운로드">Tor 및 해당 서명 다운로드</h2> <div class="sectionbody"> <div class="paragraph"> <p>Tor 브라우저 전용 폴더를 만드세요:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">mkdir -p ~/workspace/tipiak/tor cd ~/workspace/tipiak/tor</code></pre> </div> </div> <div class="paragraph"> <p>다음으로 Tor 브라우저 아카이브와 그 서명을 다운로드하세요:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">wget https://www.torproject.org/dist/torbrowser/14.5.7/tor-browser-linux-x86_64-14.5.7.tar.xz wget https://www.torproject.org/dist/torbrowser/14.5.7/tor-browser-linux-x86_64-14.5.7.tar.xz.asc</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_서명의_암호학적_검증">서명의 암호학적 검증</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 단계는<strong>필수적인</strong>다운로드한 파일이 실제로 Tor Project에서 왔는지, 그리고 수정되지 않았는지 확인하기 위해.</p> </div> <div class="sect2"> <h3 id="_1_tor_project의_공개_키_가져오기">1. Tor Project의 공개 키 가져오기</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">gpg --auto-key-locate nodefault,wkd --locate-keys torbrowser@torproject.org</code></pre> </div> </div> <div class="paragraph"> <p>키가 제대로 가져와졌는지 확인하세요 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">gpg --list-keys torbrowser@torproject.org</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_2_서명_확인">2. 서명 확인</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">gpg --verify tor-browser-linux-x86_64-14.5.7.tar.xz.asc tor-browser-linux-x86_64-14.5.7.tar.xz</code></pre> </div> </div> <div class="paragraph"> <p>모두 올바르면 다음 메시지가 표시됩니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">gpg: Good signature from "Tor Browser Developers (signing key)"</code></pre> </div> </div> <div class="paragraph"> <p>인증되지 않은 키 경고가 발생한 경우, 이는 단순히 아직 Tor Project의 신뢰 키에 서명하지 않았음을 의미하지만, 서명은 여전히 유효합니다.</p> </div> </div> <div class="sect2"> <h3 id="_실제_사례_유효한_서명이지만_인증되지_않은_키">실제 사례 : 유효한 서명이지만 인증되지 않은 키</h3> <div class="paragraph"> <p>확인 중에 이와 같은 메시지를 자주 볼 수 있습니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">gpg --verify tor-browser-linux-x86_64-14.5.7.tar.xz.asc tor-browser-linux-x86_64-14.5.7.tar.xz gpg: Signature faite le mar. 16 sept. 2025 14:26:26 CEST gpg: avec la clef RSA CAAE408AEBE2288E96FC5D5E157432CF78A65729 gpg: Bonne signature de « Tor Browser Developers (signing key) <torbrowser@torproject.org> » [inconnu] gpg: Attention : cette clef n'est pas certifiée avec une signature de confiance. gpg: Rien n'indique que la signature appartient à son propriétaire. Empreinte de clef principale : EF6E 286D DA85 EA2A 4BA7 DE68 4E2C 6E87 9329 8290 Empreinte de la sous-clef : CAAE 408A EBE2 288E 96FC 5D5E 1574 32CF 78A6 5729</code></pre> </div> </div> <div class="paragraph"> <p>이 메시지는 서명이 기술적으로 '좋음'(파일이 변경되지 않았음)을 나타내지만, GPG 시스템은 키 자체에 대한 *신뢰를 인증*할 수 없습니다. 이 의심을 해소하려면 주 키의 지문을 비교하는 것이 필수적입니다. (<code>EF6E 286D DA85 EA2A 4BA7 DE68 4E2C 6E87 9329 8290</code>) 공식 Tor Project 웹사이트에 게시된 그것과 함께</p> </div> <div class="paragraph"> <p>공식 사이트에 따르면, 예상되는 흔적은 :`EF6E286DDA85EA2A4BA7DE684E2C6E8793298290`.</p> </div> <div class="paragraph"> <p>왜냐하면 표시된 발자국`gpg`<strong>정확히</strong> 공식 사이트와 일치한다면, 키가 합법적이며 파일이 안전하다는 것을 확신할 수 있습니다. "인증되지 않은 키" 경고는 그러면 GPG 로컬 설정에 대한 정보일 뿐, 서명의 유효성이나 파일의 진위와는 관련이 없습니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_왜_서명을_검증해야_하나요">왜 서명을 검증해야 하나요?</h2> <div class="sectionbody"> <div class="paragraph"> <p>GPG 서명의 검증은 디지털 보안의 기본 행위입니다. 다음과 같이 할 수 있습니다:</p> </div> <div class="ulist"> <ul> <li> <p>보장하다<strong>진정성</strong>다운로드된 소프트웨어의</p> </li> <li> <p>악의적인 행위자가 손상시킨 파일의 설치를 방지한다</p> </li> <li> <p>참여하는<strong>디지털 주권</strong>개별적인</p> </li> <li> <p>책임감 있고 윤리적인 디지털 문화 조성</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre>@startuml left to right direction actor "사용자" as U actor "TorProject 서버" as S usecase "Tor와 그 서명을 다운로드" as D usecase "공개 키 가져오기" as K usecase "GPG 서명 확인" as V usecase "Tor를 설치하고 실행" as I U --> D U --> K U --> V U --> I S --> D @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_토르_브라우저_추출_및_실행">토르 브라우저 추출 및 실행</h2> <div class="sectionbody"> <div class="paragraph"> <p>다운로드한 압축 파일을 풀어 주세요 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">tar -xvf tor-browser-linux-x86_64-14.5.7.tar.xz cd tor-browser</code></pre> </div> </div> <div class="paragraph"> <p>그런 다음 브라우저를 실행하세요:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./start-tor-browser.desktop</code></pre> </div> </div> <div class="paragraph"> <p>첫 실행 시, Tor 네트워크에 연결하기 위한 구성 창이 열립니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_우분투_데스크톱_통합">우분투 데스크톱 통합</h2> <div class="sectionbody"> <div class="paragraph"> <p>애플리케이션 메뉴에 <strong>Tor Browser</strong> 를 추가하려면:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./start-tor-browser.desktop --register-app</code></pre> </div> </div> <div class="paragraph"> <p>다음에 할 수 있습니다:</p> </div> <div class="ulist"> <ul> <li> <p>애플리케이션 메뉴에서 <strong>Tor Browser</strong> 실행</p> </li> <li> <p>도크 즐겨찾기에 추가</p> </li> <li> <p>원하는 경우 키보드 단축키리를 만d세요</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre>@startuml start :Téléchargement de Tor; :Importation de la clé GPG; :Vérification de la signature; if (Signature valide ?) then (Oui) :Extraction du navigateur; :Lancement du navigateur Tor; :Enregistrement dans le bureau; else (Non) :Supprimer le fichier compromis; endif stop @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_tor를_이용해_교육_자료_탐색하기">Tor를 이용해 교육 자료 탐색하기</h2> <div class="sectionbody"> <div class="paragraph"> <p>Tor은 익명 도구 그 이상이다. 이는 교육 및 연구 자원에 접근할 수 있는 포털이며, 특히 다음 분야에서 그러하다:</p> </div> <div class="ulist"> <ul> <li> <p><strong>OSINT (공개 소스 정보)</strong></p> </li> <li> <p><a href="https://inteltechniques.com">https://inteltechniques.com</a></p> </li> <li> <p><a href="https://osintframework.com">https://osintframework.com</a></p> </li> <li> <p><strong>교육 공유 및 오픈 소스</strong></p> </li> <li> <p><a href="https://archive.org">https://archive.org</a>(토어를 통해 더 많은 프라이버시를 위해)</p> </li> <li> <p><a href="https://github.com/">https://github.com/</a>(Tor을 통해 이용 가능)</p> </li> <li> <p><a href="https://librarygenesis.pro">https://librarygenesis.pro</a>(무료 과학 문헌 접근)</p> </li> <li> <p><strong>지식의 전달과 디지털 사회에서의 인간의 이해</strong></p> </li> <li> <p>디지털 문화, 표현의 자유, 그리고 지식 접근에 관한 자료</p> </li> <li> <p>사이버 보안 및 기술 윤리에 대한 자유 문서</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_tor_browser_업데이트">Tor Browser 업데이트</h2> <div class="sectionbody"> <div class="paragraph"> <p>최적의 보안을 보장하기 위해 <strong>Tor Browser</strong> 를 최신 상태로 유지하는 것이 중요합니다. 브라우저에는 자동 업데이트 메커니즘이 내장되어 있어 명령줄에서 실행할 수 있습니다.</p> </div> <div class="paragraph"> <p>Tor Browser 설치 디렉토리에서 시작 스크립트를 다시 실행하기만 하면 됩니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">cd ~/workspace/tipiak/tor/tor-browser ./start-tor-browser.desktop</code></pre> </div> </div> <div class="paragraph"> <p>시작할 때, *Tor Browser*는 새 버전이 있는지 자동으로 확인합니다. 만약 새 버전이 존재한다면, 그것을 다운로드하고 설치해 드립니다.</p> </div> <div class="paragraph"> <p>이 간단한 방법은 항상 최신 보안 패치와 가장 최근의 개선 사항을 제공하여 안전한 브라우징에 필수적입니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_결론">결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>다운로드 확인은 안전한 디지털 환경에서 성장하고자 하는 모든 사람에게 필수적인 습관입니다. 검증된 방식으로 Tor를 설치하는 것은<strong>디지털 무결성 보호</strong>, <strong>무료 소프트웨어에 대한 신뢰를 유지</strong>, et <strong>정보 자율성 강화</strong>.</p> </div> <div class="paragraph"> <p>디지털 보안은 편집증이 아니라 양심의 행위이다.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml title Tor 사용 개요 actor Utilisateur rectangle "토르 브라우저" { rectangle "익명" as A rectangle "OSINT 검색" as O rectangle "교육적 공유" as E } Utilisateur --> A Utilisateur --> O Utilisateur --> E @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_참고문헌">참고문헌</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Tor Project 공식 사이트 :https://www.torproject.org/download/[<a href="https://www.torproject.org/download/" class="bare">https://www.torproject.org/download/</a>]</p> </li> <li> <p>서명 검증 문서:https://support.torproject.org/tbb/how-to-verify-signature/[<a href="https://support.torproject.org/tbb/how-to-verify-signature/" class="bare">https://support.torproject.org/tbb/how-to-verify-signature/</a>]</p> </li> <li> <p>우분투 문서:https://ubuntu.com[<a href="https://ubuntu.com" class="bare">https://ubuntu.com</a>]</p> </li> <li> <p>교육 아카이브 :https://archive.org/details/opensource[<a href="https://archive.org/details/opensource" class="bare">https://archive.org/details/opensource</a>]</p> </li> </ul> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>이 기사는 <strong>디지털 보안 및 인식</strong> 시리즈의 일부입니다, 책임감 있고 교육적인 실천을 촉진하기 위한 자유 도구 주변에서.</p> </div> </td> </tr> </table> </div> </div> </div> https://cheroliv.com/blog/2025/0093_gradle_plugin_toml_composite_build_post.html Sat, 27 Sep 2025 00:00:00 +0000 blog/2025/0093_gradle_plugin_toml_composite_build_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_소개">소개</a></li> <li><a href="#_1_버전_카탈로그_libs_versions_toml_한_가지_알림">1. 버전 카탈로그 (<code>libs.versions.toml</code>) : 한 가지 알림</a></li> <li><a href="#_2_문제_컴포지트_빌드와_두_개의_별개의_세계">2. 문제: 컴포지트 빌드와 두 개의 별개의 세계</a></li> <li><a href="#_3_솔루션_의존성_해결_공유">3. 솔루션 : 의존성 해결 공유</a></li> <li><a href="#_4_결론_잘_관리된_컴포지트_빌드의_힘">4. 결론: 잘 관리된 컴포지트 빌드의 힘</a></li> </ul> </div> <div class="sect1"> <h2 id="_소개">소개</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">대상 독자 : 멀티빌드 프로젝트에서 의존성을 관리하고 있는 Gradle 개발자</div> <p>우리의 플러그인을 만들기 위한 탐색에서`site-baker`우리는 깨끗하고 중앙집중된 코드베이스를 유지하려고 노력했습니다. 현대 Gradle 생태계에서 최고의 실천 방법 중 하나는 이를 사용하는 것입니다.<strong>버전 카탈로그</strong>(<code>libs.versions.toml</code>) 로 의존성을 관리합니다. 하지만 프로젝트가 더 복잡해질 때 무슨 일이 일어나나요, 예를 들어 하나의<strong>복합재 구축</strong>독립적인 빌드(우리의 플러그인)를 다른 곳에 포함해야 하는 곳은 어디인가요?</p> </div> <div class="paragraph"> <p>여기서 우리 모험은 예상치 못한 방향으로 바뀌었다. 우리는 우리 플러그인이`site-baker`, 그것은 자체적으로 Gradle 프로젝트인, 우리 주요 프로젝트와 동일한 버전 카탈로그를 사용한다. 이 글은, 우리 시리즈의 다섯 번째이며, 우리가 이 도전을 어떻게 해결했는지 설명한다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_1_버전_카탈로그_libs_versions_toml_한_가지_알림">1. 버전 카탈로그 (<code>libs.versions.toml</code>) : 한 가지 알림</h2> <div class="sectionbody"> <div class="paragraph"> <p>파일`gradle/libs.versions.toml`Gradle의 기능으로, 프로젝트의 의존성 버전과 좌표를 중앙 집중화할 수 있습니다. 일반적으로 네 개의 섹션으로 구성됩니다 :</p> </div> <div class="ulist"> <ul> <li> <p><code>[versions]</code>: 버전 번호에 대한 별칭을 정의합니다(예:`kotlin = "1.9.20"`).</p> </li> <li> <p><code>[libraries]</code>: 완전한 종속성에 대한 별칭을 정의하며, 위에 정의된 버전을 사용합니다(예:`kotlin-stdlib = { module = "org.jetbrains.kotlin:kotlin-stdlib", version.ref = "kotlin" }`).</p> </li> <li> <p><code>[bundles]</code>: 여러 라이브러리를 하나의 별칭으로 묶습니다 (ex:`jackson = ["jackson-core", "jackson-databind"]`).</p> </li> <li> <p><code>[plugins]</code>: Gradle 플러그인에 대한 별칭을 정의합니다.</p> </li> </ul> </div> <div class="paragraph"> <p>정의되면 Gradle은 자동으로 타입이 지정된 액세서를 생성하며, 이로 인해 귀하의`build.gradle.kts`훨씬 더 읽기 쉽습니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">dependencies { // Au lieu de : implementation("org.jetbrains.kotlin:kotlin-stdlib:1.9.20") implementation(libs.kotlin.stdlib) }</code></pre> </div> </div> <div class="listingblock"> <div class="title">버전 카탈로그의 데이터 흐름</div> <div class="content"> <pre>@startuml !theme plain file "gradle/libs.versions.toml" as Toml node "Gradle" as G file "build.gradle.kts" as BuildScript Toml --> G : "읽히기" G --> BuildScript : "접근자를 생성합니다 `libs" BuildScript -> G : "사용해 `libs` 로 종속성을 선언해" @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_2_문제_컴포지트_빌드와_두_개의_별개의_세계">2. 문제: 컴포지트 빌드와 두 개의 별개의 세계</h2> <div class="sectionbody"> <div class="paragraph"> <p>우리 프로젝트 구조는 하나의<strong>복합체 구축</strong>. 주요 프로젝트 (<code>thymeleaf.cheroliv.com</code>) 플러그인 프로젝트를 포함합니다 (<code>site-baker</code>) 명령을 통해`includeBuild("site-baker")<code>파일에서`settings.gradle.kts</code>.</p> </div> <div class="listingblock"> <div class="title">복합 빌드 구조</div> <div class="content"> <pre>@startuml !theme plain package "주요 프로젝트" { file "settings.gradle.kts" as MainSettings folder "그레이들" { file "libs.versions.toml" as MainToml } } package "플러그인 `site-baker` (포함된 빌드)" { file "settings.gradle.kts" as PluginSettings file "build.gradle.kts" as PluginBuild } MainSettings -> PluginSettings : `includeBuild("사이트 베이커")` PluginBuild ..> MainToml : **Voulait accéder à...** note right on link: ...mais ne pouvait pas ! @enduml</pre> </div> </div> <div class="paragraph"> <p>문제는 기본적으로 포함된 빌드가 하나이다<strong>별개의 세계</strong>. 그의 고유한 구성과 고유한 생명 주기를 가지고 있으며, 파일을 보지 못한다`libs.versions.toml`주요 빌드. 우리`plugin/build.gradle.kts`사용하려고 노력하고 있었다`libs.plugins.kotlin.jvm`, 그러나 그 객체`libs`올바른 TOML 파일에서 생성되지 않아서 빌드 오류가 발생했습니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_3_솔루션_의존성_해결_공유">3. 솔루션 : 의존성 해결 공유</h2> <div class="sectionbody"> <div class="paragraph"> <p>여러 차례의 연구 끝에, 해결책이 이 경우를 정확히 위해 설계된 Gradle 기능임이 밝혀졌습니다:`dependencyResolutionManagement`.</p> </div> <div class="paragraph"> <p>파일에`settings.gradle.kts` du <strong>포괄적인 빌드</strong> (<code>site-baker/settings.gradle.kts</code>), 우리는 Gradle에게 사용할 버전 카탈로그를 어디서 찾을 수 있는지 알려줄 수 있습니다.</p> </div> <div class="paragraph"> <p>다음은 우리가 추가한 구성`site-baker/settings.gradle.kts`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// site-baker/settings.gradle.kts dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { gradlePluginPortal() mavenCentral() } versionCatalogs { create("libs") { from(files("../gradle/libs.versions.toml")) } } } rootProject.name = "site-baker" include("plugin")</code></pre> </div> </div> <div class="paragraph"> <p>핵심 부분을 분석해 봅시다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">versionCatalogs { create("libs") { // Crée un catalogue nommé 'libs' from(files("../gradle/libs.versions.toml")) // En utilisant ce fichier } }</code></pre> </div> </div> <div class="ulist"> <ul> <li> <p><code>create("libs")`우리는 별칭을 통해 접근 가능한 버전 카탈로그를 선언합니다`libs</code>.</p> </li> <li> <p><code>from(files("../gradle/libs.versions.toml"))</code>: 이것은 마법입니다. 우리는 Gradle에게 이 카탈로그의 소스가 디렉터리에 위치한 TOML 파일이라고 나타냅니다.<code>gradle</code> du <strong>상위 프로젝트</strong>(</p> </li> </ul> </div> <div class="paragraph"> <p>(Note: The output includes a leading space and an opening parenthesis as in the source, with no additional text.)<code>../</code>)</p> </div> <div class="paragraph"> <p>이 구성으로 빌드`site-baker`이제 그는 메인 프로젝트의 버전 카탈로그를 사용해야 한다는 것을 알고 있습니다. 객체`libs`정상적으로 생성되며, 종속성이 예상대로 해결됩니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_4_결론_잘_관리된_컴포지트_빌드의_힘">4. 결론: 잘 관리된 컴포지트 빌드의 힘</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 경험은 많은 교훈을 제공했습니다. 버전 카탈로그는 유지보수성을 위한 훌륭한 도구이지만, 복합 빌드 시나리오에서의 동작은 항상 직관적이지 않습니다.</p> </div> <div class="paragraph"> <p>핵심은 포함된 빌드가 여전히 독립된 빌드라는 사실을 기억하는 것입니다. 버전 카탈로그와 같은 구성 설정을 공유하려면 Gradle이 제공하는 명시적인 메커니즘, 예를 들어 블록을 사용해야 합니다.<code>dependencyResolutionManagement`안에`settings.gradle.kts</code>.</p> </div> <div class="paragraph"> <p>이 문제를 해결함으로써 우리는 단순히 빌드를 더 깨끗하게 만들었을 뿐만 아니라, 플러그인과 메인 프로젝트가 의존성에 대한 단일 진실의 출처를 공유하도록 함으로써 프로젝트의 일관성도 강화했습니다.</p> </div> <div class="paragraph"> <p>다음 기사에서는 의존성 관리가 강력하고 중앙 집중화되었으므로 이제 더 복잡한 작업을 추가하여 플러그인을 계속 풍부하게 할 것입니다.</p> </div> </div> </div> https://cheroliv.com/blog/2025/0092_gradle_configuration_cache_post.html Fri, 26 Sep 2025 00:00:00 +0000 blog/2025/0092_gradle_configuration_cache_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_서론">서론</a></li> <li><a href="#_증상_유령의_빌드">증상: 유령의 빌드</a></li> <li><a href="#_조사_구성_캐시는_무엇입니까">조사: 구성 캐시는 무엇입니까?</a></li> <li><a href="#_문제의_원인_비준수_플러그인">문제의 원인: 비준수 플러그인</a></li> <li><a href="#_임시_솔루션_캐시_비활성화">임시 솔루션: 캐시 비활성화</a></li> <li><a href="#_진정한_해결책_플러그인_호환성_확보">진정한 해결책: 플러그인 호환성 확보</a></li> </ul> </div> <div class="sect1"> <h2 id="_서론">서론</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">대상 : Gradle 개발자 중에서 이미 '매직’하거나 예상치 못한 빌드 동작을 경험한 사람들</div> <p>플러그인을 만드는 우리의 모험`site-baker`, 우리는 엄격한 TDD 접근 방식을 따랐습니다. 각 기능은 테스트되고, 검증되었으며, 우리는 확신을 가지고 진행했습니다. 그리고ある日, 예기치 못한 일이 발생했습니다. 빌드가 예측할 수 없이 동작하기 시작했습니다. 플러그인 로직이나 구성 파일의 수정이 무시되는 것처럼 보였고, 이전에 신뢰할 수 있었던 기능 테스트가 명백한 이유 없이 실패하기 시작했습니다.</p> </div> <div class="paragraph"> <p>이러한 종류의 문제는 믿을 수 없을 정도로 좌절스러울 수 있습니다. 이는 도구의 안정성과 우리의 코드의 유효성을 의심하게 만듭니다. 강도 높은 디버깅 세션 후, 범인이 밝혀졌습니다: 그<strong>Gradle 구성 캐시</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_증상_유령의_빌드">증상: 유령의 빌드</h2> <div class="sectionbody"> <div class="paragraph"> <p>문제가 여러 가지 방식으로 나타났습니다 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>저는 한 작업에서 문자열을 수정하고 있었습니다.<code>println</code>, 하지만 이전 문자열이 실행 중에 계속 표시되었습니다.</p> </li> <li> <p>저는 내 파일에서 값을 바꾸고 있었습니다.<code>managed-jbake-context.yml</code>, 하지만 플러그인은 파일이 수정된 것처럼 행동했습니다.</p> </li> <li> <p>기능 테스트는 즉석에서 테스트 프로젝트를 만들지만, 플러그인이 새로 생성된 구성 파일을 감지하지 못하는 것 같아서 실패했습니다.</p> </li> </ol> </div> <div class="paragraph"> <p>모든 것이 마치 Gradle가 우리 빌드의 '유령 버전’을 실행하는 것처럼 진행되고 있었고, 우리의 가장 최근 변경 사항을 무시하고 있었다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_조사_구성_캐시는_무엇입니까">조사: 구성 캐시는 무엇입니까?</h2> <div class="sectionbody"> <div class="paragraph"> <p>구성 캐시는 비교적 최신이면서 매우 강력한 Gradle의 기능이며, 최신 버전에서는 기본적으로 활성화됩니다. 그 목적은 빌드를 더 빠르게 만드는 것입니다.</p> </div> <div class="olist arabic"> <div class="title">원칙은 간단합니다 :</div> <ol class="arabic"> <li> <p>첫 번째 실행 시, Gradle은 단계를 실행합니다.<strong>구성</strong>(읽기의`build.gradle.kts`, 작업 생성, 의존성 해결) 그리고 작업 그래프를 구성한다</p> </li> <li> <p>이 단계가 끝날 때, Gradle<strong>이 작업 그래프 직렬화</strong>그리고 그것을 캐시에 저장합니다.</p> </li> <li> <p>이후 실행 시, 아무것도 변경되지 않은 경우 (빌드 스크립트,<code>gradle.properties</code>, etc.), Gradle<strong>설정 단계를 완전히 건너뛴다</strong>그리고 캐시된 작업 그래프를 재사용합니다.</p> </li> </ol> </div> <div class="paragraph"> <p>시간 절약이 큰 프로젝트에서 놀라울 정도입니다. 그러나 이 성능에는 대가가 따릅니다: 플러그인이 어떻게 작성되어야 하는지에 대해 엄격한 규칙을 적용합니다.</p> </div> <div class="listingblock"> <div class="title">구성 캐시의 수명 주기</div> <div class="content"> <pre>@startuml start :Première exécution; :Phase de Configuration; :Création du graphe de tâches; :Mise en cache du graphe; :Phase d'Exécution; end start :Exécution suivante; if (Cache valide ?) then (oui) :Restauration du graphe depuis le cache; note right La phase de configuration est sautée ! end note else (non) :Phase de Configuration; :Mise à jour du cache; endif :Phase d'Exécution; stop @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_문제의_원인_비준수_플러그인">문제의 원인: 비준수 플러그인</h2> <div class="sectionbody"> <div class="paragraph"> <p>우리 플러그인`site-baker`그는 알지 못한 채 구성 캐시의 여러 규칙을 위반하고 있었다. 작업 그래프가 직렬화 가능하려면, 작업은 복합 객체와 같은 참조를 포함해서는 안 된다.`Project`또는 실행 단계에서 임의로 파일을 읽을 수 있습니다.</p> </div> <div class="paragraph"> <p>주요 오류는 확장 프로그램에 저장된 경로 참조를 사용하여 작업 실행 로직 내에서 YAML 파일의 내용을 직접 읽는 것이었습니다. 이 방식은 Gradle이 파일 내용이 변경되었는지 알 수 없도록 이 읽기를 모델링하지 않으면 캐시와 호환되지 않습니다.<strong>작업 항목</strong>(작업 입력).</p> </div> </div> </div> <div class="sect1"> <h2 id="_임시_솔루션_캐시_비활성화">임시 솔루션: 캐시 비활성화</h2> <div class="sectionbody"> <div class="paragraph"> <p>우리의 막힘을 풀고 예측 가능한 빌드 동작을 되찾기 위해 가장 빠른 해결 방법은 구성 캐시를 비활성화하는 것이었습니다. 파일에 다음 줄을 추가하기만 하면 됩니다.<code>gradle.properties`플러그인을 사용하는 프로젝트 (또는 우리 경우, 테스트 프로젝트)`site-baker</code>).</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties"># site-baker/gradle.properties org.gradle.configuration-cache=false</code></pre> </div> </div> <div class="paragraph"> <p>즉시, 빌드가 정상적인 동작을 되찾았습니다. 각 실행이 구성 단계를 다시 실행했고, 우리의 변경 사항이 반영되었습니다.</p> </div> <div class="paragraph"> <p>그러나 이것은 임시방편이 아니라 지속 가능한 해결책이 아닙니다. 성능을 희생시키고 우리 플러그인의 근본적인 문제를 해결하지 못합니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_진정한_해결책_플러그인_호환성_확보">진정한 해결책: 플러그인 호환성 확보</h2> <div class="sectionbody"> <div class="paragraph"> <p>플러그인이 현대 Gradle 생태계의 좋은 시민이 되려면 구성 캐시와 호환되어야 합니다. 이는 우리 작업으로 데이터가 흐르는 방식을 재고해야 함을 의미합니다.</p> </div> <div class="paragraph"> <p>핵심은 그것을 사용하는<strong>제공자 API</strong>Gradle의. 직접적인 값을 전달하는 대신 (예를 들어`String` ou un <code>File</code>) 우리의 작업에 대해, 우리는 통과해야 합니다`Property<T>`또는 일부의`Provider<T>`.</p> </div> <div class="paragraph"> <p>다음은 리팩터링 계획입니다 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>작업 항목 선언 :</strong>YAML 파일을 파싱하는 작업은 이 파일을 입력으로 선언해야 합니다. 이를 위해 어노테이션을 사용합니다.<code>@InputFile</code>.</p> </li> </ol> </div> <div class="paragraph"> <p>[source,kotlin] ---- @get:InputFile abstract val configFile: RegularFileProperty ----</p> </div> <div class="listingblock"> <div class="content"> <pre></pre> </div> </div> </div> </div> https://cheroliv.com/blog/2025/0091_jackson_yaml_tdd_post.html Thu, 25 Sep 2025 00:00:00 +0000 blog/2025/0091_jackson_yaml_tdd_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_소개">소개</a></li> <li><a href="#_컨텍스트_우리_플러그인_site_baker">컨텍스트 : 우리 플러그인 `site-baker</a></li> <li><a href="#_2_코틀린에서의_구성_모델링">2. 코틀린에서의 구성 모델링</a></li> <li><a href="#_3_jackson을_build_gradle_kts에_통합">3. Jackson을 `build.gradle.kts`에 통합</a></li> <li><a href="#_4_tdd_접근_방식_yaml_파싱_테스트">4. TDD 접근 방식 : YAML 파싱 테스트</a> <ul class="sectlevel2"> <li><a href="#_4_1_단위_테스트_yaml을_kotlin_객체에_매핑하기">4.1. 단위 테스트 : YAML을 Kotlin 객체에 매핑하기</a></li> <li><a href="#_4_2_기능_테스트_구성_파일_읽기_검증">4.2. 기능 테스트 : 구성 파일 읽기 검증</a></li> </ul> </li> <li><a href="#_5_파싱_흐름_시각화">5. 파싱 흐름 시각화</a></li> <li><a href="#_결론">결론</a></li> </ul> </div> <div class="sect1"> <h2 id="_소개">소개</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">대상 : 복잡한 구성을 관리하려는 중급 Gradle 개발자</div> <p>Gradle 플러그인 개발에서 복잡한 구성 관리는 일반적인 작업입니다. 백 개 이상의 속성으로 DSL을 과부하 시키는 대신, 외부 파일(YAML과 같은)에 구성을 정의하는 것이 종종 더 깔끔하고 유지 관리하기 쉽습니다. 이 글에서는 강력한 Jackson 라이브러리를 통합하여 YAML 파일을 Kotlin 객체로 파싱하는 과정을 안내하며, 플러그인의 견고함을 보장하기 위해 엄격한 TDD 접근 방식을 채택합니다.<code>site-baker</code>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_컨텍스트_우리_플러그인_site_baker">컨텍스트 : 우리 플러그인 `site-baker</h2> <div class="sectionbody"> <div class="paragraph"> <p>우리 플러그인`site-baker`정적 사이트의 생성과 배포를 자동화하도록 설계되었습니다. YAML 설정 파일을 읽어야 합니다 (<code>managed-jbake-context.yml</code>) 소스 경로, 배포 대상, Git 식별자와 같은 정보를 얻으려면</p> </div> <div class="paragraph"> <p>파싱하고자 하는 YAML 구성은 다음과 같습니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">bake: srcPath: "./site/jbake" destDirPath: "bake" cname: "cheroliv.com" pushPage: from: "bake" to: "cvs" repo: name: "trainings" repository: "https://github.com/pages-content/pages-content.github.io.git" credentials: username: "USERNAME" password: "SECRET_TOKEN" branch: "main" message: "cheroliv.com" # ... autres configurations (pushMaquette, supabase, etc.)</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_2_코틀린에서의_구성_모델링">2. 코틀린에서의 구성 모델링</h2> <div class="sectionbody"> <div class="paragraph"> <p>파싱하기 전에 Kotlin에서 데이터 구조를 정의해야 합니다. Jackson은 이러한 클래스를 사용하여 YAML 내용을 자동으로 매핑합니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// plugin/src/main/kotlin/com/cheroliv/site/baker/data/SiteConfiguration.kt package com.cheroliv.site.baker.data import com.fasterxml.jackson.databind.ObjectMapper import com.fasterxml.jackson.dataformat.yaml.YAMLFactory import com.fasterxml.jackson.module.kotlin.readValue import com.fasterxml.jackson.module.kotlin.registerKotlinModule fun parseSiteConfiguration(yaml: String): SiteConfiguration { val mapper = ObjectMapper(YAMLFactory()).registerKotlinModule() return mapper.readValue(yaml) } data class GitPushConfiguration( val from: String = "", val to: String = "", val repo: RepositoryConfiguration = RepositoryConfiguration(), val branch: String = "", val message: String = "", ) data class RepositoryConfiguration( val name: String = "", val repository: String = "", val credentials: RepositoryCredentials = RepositoryCredentials(), ) { companion object { const val ORIGIN = "origin" const val CNAME = "CNAME" const val REMOTE = "remote" } } data class RepositoryCredentials(val username: String = "", val password: String = "") data class SiteConfiguration( val bake: BakeConfiguration = BakeConfiguration(), val pushPage: GitPushConfiguration = GitPushConfiguration(), val pushMaquette: GitPushConfiguration = GitPushConfiguration(), val pushSource: GitPushConfiguration? = null, val pushTemplate: GitPushConfiguration? = null, val supabase: SupabaseContactFormConfig? = null ) data class BakeConfiguration( val srcPath: String = "", val destDirPath: String = "", val cname: String? = null, ) // ... (autres data classes pour Supabase, si nécessaire)</code></pre> </div> </div> <div class="paragraph"> <p>기능`parseSiteConfiguration`는 역직렬화를 위한 진입점입니다. 그녀는 사용합니다`ObjectMapper`Jackson의, 구성된`YAMLFactory`YAML 형식과`registerKotlinModule()`Kotlin의 특정 기능을 지원하기 위해 (속성의 기본값과 같은).</p> </div> </div> </div> <div class="sect1"> <h2 id="_3_jackson을_build_gradle_kts에_통합">3. Jackson을 `build.gradle.kts`에 통합</h2> <div class="sectionbody"> <div class="paragraph"> <p>Jackson을 사용하려면, 필요한 종속성을 추가해야 합니다. 안에`build.gradle.kts`우리 모듈의`plugin`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// plugin/build.gradle.kts dependencies { // Jackson for YAML parsing implementation("com.fasterxml.jackson.module:jackson-module-kotlin:2.18.3") implementation("com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.18.3") // ... autres dépendances }</code></pre> </div> </div> <div class="paragraph"> <p>우리는 사용합니다`jackson-module-kotlin`Kotlin 지원과`jackson-dataformat-yaml`YAML 형식 관리를 위해</p> </div> </div> </div> <div class="sect1"> <h2 id="_4_tdd_접근_방식_yaml_파싱_테스트">4. TDD 접근 방식 : YAML 파싱 테스트</h2> <div class="sectionbody"> <div class="paragraph"> <p>이제 TDD를 적용하여 파싱 논리를 검증해 봅시다.</p> </div> <div class="sect2"> <h3 id="_4_1_단위_테스트_yaml을_kotlin_객체에_매핑하기">4.1. 단위 테스트 : YAML을 Kotlin 객체에 매핑하기</h3> <div class="paragraph"> <p>우리는 단위 테스트로 시작합니다`SiteBakerPluginTest.kt`함수가 올바르게 작동하는지 확인하기 위해`parseSiteConfiguration`YAML 문자열을 개체로 올바르게 변환할 수 있습니다.<code>SiteConfiguration</code>.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// plugin/src/test/kotlin/com/cheroliv/site/baker/SiteBakerPluginTest.kt @Test fun `can map configuration text to SiteConfiguration object`() { val yamlString = "../../managed-jbake-context.yml" .run(::File) .readText() .trimIndent() val config: SiteConfiguration = parseSiteConfiguration(yamlString) assertEquals("cheroliv.com", config.bake.cname) assertEquals("main", config.pushPage.branch) assertEquals("https://github.com/pages-content/pages-content.github.io.git", config.pushPage.repo.repository) }</code></pre> </div> </div> <div class="paragraph"> <p>이 테스트는 파일의 내용을 읽는다`managed-jbake-context.yml`(테스트가 유효하려면 존재해야 하는) 그리고 객체에 대해 어서션을 수행합니다`SiteConfiguration`결과적으로. YAML의 키 값이 올바르게 매핑되었는지 검증합니다.</p> </div> </div> <div class="sect2"> <h3 id="_4_2_기능_테스트_구성_파일_읽기_검증">4.2. 기능 테스트 : 구성 파일 읽기 검증</h3> <div class="paragraph"> <p>플러그인이 DSL을 통해 구성 파일을 읽을 수 있도록 보장하고 실제 Gradle 환경에서 파싱이 동작하도록 하기 위해 기능 테스트를 추가합니다.<code>SiteBakerPluginFunctionalTest.kt</code>.</p> </div> <div class="paragraph"> <p>이 테스트는 실제 프로젝트에서 플러그인 실행을 시뮬레이션하기 때문에 중요합니다. 이것은<strong>밀폐된</strong>, 즉, 그가 직접 파일을 만들어야 한다는 뜻이다.`managed-jbake-context.yml`통제된 내용으로, 테스트의 재현성과 격리를 보장하기 위해</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// plugin/src/functionalTest/kotlin/com/cheroliv/site/baker/SiteBakerPluginFunctionalTest.kt @Test fun `config file contains good data`(){ val configContent = configFile.readText(UTF_8) // Vérifications comme dans vos commentaires assertTrue(configContent.contains("bake")) assertTrue(configContent.contains("pushPage")) assertTrue(configContent.contains("repository")) }</code></pre> </div> </div> <div class="paragraph"> <p>이 기능 테스트는 테스트의 임시 디렉터리에 복사된 구성 파일이 예상된 데이터를 포함하고 있는지 확인합니다. 이 테스트는 YAML을 Kotlin 객체로 직접 파싱하지는 않지만, 파일의 존재와 내용을 검증하며, 이는 플러그인에 의한 파싱을 위한 필수적인 사전 단계입니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_5_파싱_흐름_시각화">5. 파싱 흐름 시각화</h2> <div class="sectionbody"> <div class="paragraph"> <p>다음 다이어그램은 YAML 구성 파싱 중 데이터 흐름과 상호작용을 보여줍니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml actor "사용자 Gradle" as User participant "build.gradle.kts" as BuildScript participant "SiteBakerPlugin" as Plugin participant "사이트 확장" as Extension participant "managed-jbake-context.yml" as ConfigFile participant "parseSiteConfiguration()" as Parser participant "SiteConfiguration (Kotlin 객체)" as KotlinObject User -> BuildScript : Applique le plugin et configure le DSL BuildScript -> Plugin : apply() Plugin -> Extension : Crée et enregistre l'extension 'site' User -> BuildScript : site { configPath = "..." } BuildScript -> Extension : Définit configPath Plugin -> ConfigFile : Lit le fichier (via configPath) ConfigFile --> Plugin : Contenu YAML Plugin -> Parser : Appelle parseSiteConfiguration(yamlString) Parser -> KotlinObject : Mappe le YAML en objet SiteConfiguration KotlinObject --> Plugin : Retourne l'objet configuré @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_결론">결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>TDD 방식을 따르면서 Jackson 라이브러리를 성공적으로 통합하여 Gradle 플러그인 내에서 YAML 구성 파일을 Kotlin 객체로 파싱했습니다. 이를 통해 우리는 다음과 같이 할 수 있게 되었습니다 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>명확히 모델링</strong>우리의 Kotlin 데이터 클래스를 사용한 구성.</p> </li> <li> <p><strong>파싱 로직 검증</strong>대상화된 단위 테스트와 함께.</p> </li> <li> <p><strong>통합을 보장하다</strong>실제 Gradle 환경에서 허메틱 기능 테스트를 통해</p> </li> </ul> </div> <div class="paragraph"> <p>이 견고한 기반은 이 구성을 기반으로 하는 기능을 갖춘 우리 플러그인을 확장할 수 있는 큰 확신을 제공하며, 동시에 코드의 유지 관리 가능성과 안정성을 보장합니다. YAML 파싱은 이제 우리 플러그인의 신뢰할 수 있고 테스트된 기능이 되었습니다.<code>site-baker</code>.</p> </div> </div> </div> https://cheroliv.com/blog/2025/0090_TDD_gradle_plugin_post.html Wed, 24 Sep 2025 00:00:00 +0000 blog/2025/0090_TDD_gradle_plugin_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_1_프로젝트_초기화">1. 프로젝트 초기화</a></li> <li><a href="#_2_우리_첫_번째_tdd_사이클_작업_기록하기">2. 우리 첫 번째 TDD 사이클: 작업 기록하기</a> <ul class="sectlevel2"> <li><a href="#_2_1_먼저_테스트_실패하는_테스트">2.1. 먼저 테스트 (실패하는 테스트)</a></li> <li><a href="#_2_2_코드_다음_테스트_통과하기">2.2. 코드 다음 (테스트 통과하기)</a></li> </ul> </li> <li><a href="#_3_두_번째_tdd_사이클_dsl_확장_추가">3. 두 번째 TDD 사이클: DSL 확장 추가</a> <ul class="sectlevel2"> <li><a href="#_3_1_먼저_테스트">3.1. 먼저 테스트</a></li> <li><a href="#_3_2_다음_코드">3.2. 다음 코드</a></li> </ul> </li> <li><a href="#_4_기능_테스트_통합_검증">4. 기능 테스트 : 통합 검증</a> <ul class="sectlevel2"> <li><a href="#_4_1_통합_테스트_통제된_환경_만들기">4.1. 통합 테스트: 통제된 환경 만들기</a></li> <li><a href="#_4_2_논리_최종화">4.2. 논리 최종화</a></li> </ul> </li> <li><a href="#_결론">결론</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>이 글에서는 테스트 주도 개발(TDD) 접근법을 사용해 Gradle 플러그인을 위한 견고한 개발 기반을 구축하는 방법을 탐구해 보겠습니다. 이 방법은 우리 코드가 처음부터 견고하고 유지 가능하며 요구 사항을 정확히 충족하도록 보장합니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_1_프로젝트_초기화">1. 프로젝트 초기화</h2> <div class="sectionbody"> <div class="paragraph"> <p>Gradle은 명령을 통해 새로운 플러그인 생성을 매우 쉽게 합니다`gradle init`. Kotlin을 사용하여 Gradle 플러그인을 만들기로 선택하면, 바로 사용할 수 있는 프로젝트 구조를 얻을 수 있으며, 여기에는 두 가지 중요한 유형의 테스트가 포함됩니다 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>단위 테스트 :</strong>에 위치한`src/test`, 그들은 플러그인의 격리된 구성 요소, 예를 들어 작업의 내부 로직이나 확장 구성을 검증할 수 있도록 허용합니다. 그들은 빠르며 Gradle의 전체 실행이 필요하지 않습니다.</p> </li> <li> <p><strong>기능 테스트 :</strong>에 위치한`src/functionalTest`, 그들은 사용합니다`GradleRunner`임시 테스트 프로젝트에서 완전한 Gradle 빌드를 실행하기 위해. 이를 통해 통제된 환경에서 플러그인의 실제 동작을 확인할 수 있다.</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_2_우리_첫_번째_tdd_사이클_작업_기록하기">2. 우리 첫 번째 TDD 사이클: 작업 기록하기</h2> <div class="sectionbody"> <div class="paragraph"> <p>첫 번째 요구사항은 간단합니다: 플러그인은 이름을 가진 작업을 기록해야 합니다.<code>printSiteConfig</code>.</p> </div> <div class="sect2"> <h3 id="_2_1_먼저_테스트_실패하는_테스트">2.1. 먼저 테스트 (실패하는 테스트)</h3> <div class="paragraph"> <p>TDD에 따라, 우리는 먼저 이 작업의 존재를 확인하는 테스트를 작성합니다. 안에`SiteBakerPluginTest.kt`(우리 단위 테스트 파일), 우리는 추가합니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `plugin registers task`() { // Créer un projet de test en mémoire val project = ProjectBuilder.builder().build() project.plugins.apply("com.cheroliv.site-baker") // Vérifier que la tâche a bien été enregistrée assertNotNull(project.tasks.findByName("printSiteConfig")) }</code></pre> </div> </div> <div class="paragraph"> <p>이 테스트가 실패하는 이유는, 아직 플러그인에 코드를 전혀 작성하지 않았기 때문입니다.</p> </div> </div> <div class="sect2"> <h3 id="_2_2_코드_다음_테스트_통과하기">2.2. 코드 다음 (테스트 통과하기)</h3> <div class="paragraph"> <p>이제 우리는 안에 필요한 최소한의 코드를 작성합니다`SiteBakerPlugin.kt`테스트가 통과하도록 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class SiteBakerPlugin: Plugin<Project> { override fun apply(project: Project) { // Enregistrer une tâche simple project.tasks.register("printSiteConfig") { task -> // ... la logique de la tâche viendra plus tard } } }</code></pre> </div> </div> <div class="paragraph"> <p>우리는 테스트를 다시 실행하고, 그들은 통과합니다. 우리의 첫 번째 기능이 검증되었습니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_3_두_번째_tdd_사이클_dsl_확장_추가">3. 두 번째 TDD 사이클: DSL 확장 추가</h2> <div class="sectionbody"> <div class="paragraph"> <p>다음 요구사항은 사용자가 DSL 블록을 통해 우리 플러그인을 구성할 수 있도록 하는 것, 그들의`build.gradle.kts`. 우리는 하나의 블록을 원합니다.`site { …​ }`구성 경로를 지정할 수 있는.</p> </div> <div class="sect2"> <h3 id="_3_1_먼저_테스트">3.1. 먼저 테스트</h3> <div class="paragraph"> <p>우리는 확장이 정상인지 확인하기 위해 테스트를 추가합니다.`site`잘 기록되어 있고 거기에 값을 할당할 수 있습니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `plugin registers extension`() { val project = ProjectBuilder.builder().build() project.plugins.apply("com.cheroliv.site-baker") // Récupérer l'extension et lui affecter une valeur project.extensions .findByType(SiteExtension::class.java)!! .configPath .set("config.yml") // Vérifier que la valeur a bien été prise en compte assertEquals( "config.yml", project.extensions.findByType(SiteExtension::class.java)?.configPath?.get() ) }</code></pre> </div> </div> <div class="paragraph"> <p>이 테스트는 실패했는데 클래스가 도이고`SiteExtension`확장 프로그램 등록도 존재하지 않습니다.</p> </div> </div> <div class="sect2"> <h3 id="_3_2_다음_코드">3.2. 다음 코드</h3> <div class="paragraph"> <p>우리는 클래스를 만듭니다`SiteBakerExtension.kt`그리고 업데이트합니다`SiteBakerPlugin.kt`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// SiteBakerExtension.kt open class SiteExtension @Inject constructor(objects: ObjectFactory) { val configPath: Property<String> = objects.property(String::class.java) } // SiteBakerPlugin.kt class SiteBakerPlugin: Plugin<Project> { override fun apply(project: Project) { // Enregistrer l'extension val extension = project.extensions.create("site", SiteExtension::class.java) project.tasks.register("printSiteConfig") { task -> task.doLast { // On utilisera l'extension plus tard } } } }</code></pre> </div> </div> <div class="paragraph"> <p>테스트가 다시 통과됩니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_4_기능_테스트_통합_검증">4. 기능 테스트 : 통합 검증</h2> <div class="sectionbody"> <div class="paragraph"> <p>이제 단위가 테스트되었으므로, 실제 빌드에서 모든 것이 함께 작동하는지 확인해야 합니다. 이는 기능 테스트의 역할이다`SiteBakerPluginFunctionalTest.kt`.</p> </div> <div class="sect2"> <h3 id="_4_1_통합_테스트_통제된_환경_만들기">4.1. 통합 테스트: 통제된 환경 만들기</h3> <div class="paragraph"> <p>이 테스트는 우리 플러그인을 사용하는 실제 프로젝트를 시뮬레이션할 것입니다. 신뢰할 수 있도록 하려면 이 테스트는 신뢰할 수 있어야 합니다.<strong>기밀한</strong>, 즉, 시스템에 존재하는 파일에 의존해서는 안 된다. 직접 모든 실행에 필요한 조건을 만들어야 한다.</p> </div> <div class="paragraph"> <p>따라서 테스트는 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>생성하는`build.gradle.kts`우리 플러그인 및 DSL을 사용하는 테스트</p> </li> <li> <p><strong>구성 파일 만들기</strong>(<code>managed-jbake-context.yml</code>) 플러그인이 읽어야 할 내용입니다. 이것은 테스트의 견고성을 위한 중요한 단계입니다.</p> </li> <li> <p>작업을 실행하다`printSiteConfig`경유하여`GradleRunner`.</p> </li> <li> <p>빌드 출력이 올바른지 확인하세요.</p> </li> </ol> </div> <div class="paragraph"> <p>이 구성 파일을 복사하거나 만들 때마다 실행함으로써, 우리는 테스트가 보장됨을 확신합니다.<strong>재현 가능한</strong>그리고 외부 상태에 의존하지 않습니다. 이는 파일을 읽는 것과 관련될 수 있는 회귀로부터 우리의 테스트를 보호합니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `can run task with DSL`() { // 1. Créer un build.gradle.kts de test buildFile.writeText(""" plugins { id("com.cheroliv.site-baker") } site { configPath = "managed-jbake-context.yml" } """.trimIndent()) // 2. Créer le fichier de configuration pour un test contrôlé val configFile = File(projectDir, "managed-jbake-context.yml") configFile.writeText("site: { title: 'Mon Site de Test' }") // Contenu YAML simple // 3. Exécuter la build val runner = GradleRunner.create() runner.withPluginClasspath() runner.withArguments("printSiteConfig") runner.withProjectDir(projectDir) // Spécifier le répertoire du projet de test val result = runner.build() // 4. Vérifier la sortie assertTrue(result.output.contains("Site config path: managed-jbake-context.yml")) }</code></pre> </div> </div> <div class="paragraph"> <p>이 테스트는 작업이 끝날 때까지 실패할 것입니다.`printSiteConfig`확장 기능의 값을 실제로 사용하지 않을 것입니다.</p> </div> </div> <div class="sect2"> <h3 id="_4_2_논리_최종화">4.2. 논리 최종화</h3> <div class="paragraph"> <p>우리는 작업을 업데이트하고 있습니다`SiteBakerPlugin.kt`설정된 값을 표시하도록 하기:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">project.tasks.register("printSiteConfig") { task -> task.doLast { println("Site config path: ${extension.configPath.get()}") } }</code></pre> </div> </div> <div class="paragraph"> <p>모든 테스트, 단위 및 기능 테스트, 이제는 통과합니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_결론">결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>TDD 방식을 따라 점진적이고 안전하게 플러그인을 구축했습니다. 작은 기능 하나하나를 테스트로 즉시 검증하며, 빠른 단위 테스트부터 완전한 통합을 검증하는 기능 테스트까지 수행합니다.</p> </div> <div class="paragraph"> <p>테스트가 정상적으로 작동하도록 주의하면서<strong>밀폐된</strong>— 필요에 따라 프로그래밍 방식으로 필요한 구성 파일을 생성함으로써 — 우리는 매우 견고한 안전망을 구축합니다. 이 엄격함은 회귀에 효과적으로 대처하고 향후 더 복잡한 기능을 추가할 수 있는 큰 자신감을 줍니다. 예를 들어 YAML 구성 파일 파싱과 같이.</p> </div> <div class="paragraph"> <p>이 강력한 테스트베이스는 플러그인의 유지보수와 미래 발전을 위한 가장 귀중한 자산입니다.</p> </div> </div> </div> https://cheroliv.com/blog/2025/0089_creation_projet_plugin_gradle_post.html Tue, 23 Sep 2025 00:00:00 +0000 blog/2025/0089_creation_projet_plugin_gradle_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_소개">소개</a></li> <li><a href="#_1단계_프로젝트_어시스턴트_실행">1단계: 프로젝트 어시스턴트 실행</a></li> <li><a href="#_2단계_생성된_구조_이해하기">2단계: 생성된 구조 이해하기</a> <ul class="sectlevel2"> <li><a href="#_주요_파일_및_폴더">주요 파일 및 폴더</a></li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_소개">소개</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">l대상 : 초중급 Gradle 개발자.</div> <p>Gradle 플러그인 새 프로젝트를 시작하는 것은 위협적으로 느껴질 수 있습니다. 다행히도, Gradle은 강력한 대화형 어시스턴트를 제공합니다, 작업`init`, 완전하고 깔끔하며 즉시 사용 가능한 프로젝트 구조를 생성하는. 이 가이드는 이 도구를 사용하여 건강한 플러그인 베이스를 만드는 방법을 보여주고, 구조를 설명하며, 처음 빌드 작업을 시작하는 방법을 보여줄 것입니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_1단계_프로젝트_어시스턴트_실행">1단계: 프로젝트 어시스턴트 실행</h2> <div class="sectionbody"> <div class="paragraph"> <p>명령`gradle init`은 시작점입니다. 그녀는 명령줄 어시스턴트를 실행하여 프로젝트를 구성하기 위한 일련의 질문을 던집니다.</p> </div> <div class="paragraph"> <p>빈 폴더에서 터미널을 열고 실행하세요:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">gradle init</code></pre> </div> </div> <div class="paragraph"> <p>어시스턴트가 안내해 드릴 것입니다. 다음은 Kotlin으로 작성된 Gradle 플러그인에 대한 선택 사항입니다:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>생성할 프로젝트 유형을 선택하세요:</strong>선택하세요`Gradle plugin`.</p> </li> <li> <p><strong>구현 언어를 선택하세요:</strong>선택하세요`Kotlin`.</p> </li> <li> <p><strong>빌드 스크립트 DSL 선택:</strong>선택하세요`Kotlin`.</p> </li> <li> <p><strong>프로젝트 이름:</strong>프로젝트에 이름을 입력하세요 (예:`site-baker`).</p> </li> <li> <p><strong>플러그인 id:</strong>플러그인에 고유한 식별자를 지정하세요 (예:`com.cheroliv.site-baker`).</p> </li> <li> <p><strong>플러그인 클래스:</strong>구현 클래스의 이름을 지정하세요 (예:`com.cheroliv.SiteBakerPlugin`)</p> </li> </ol> </div> <div class="paragraph"> <p>완료 후, Gradle은 완전한 파일 트리를 생성합니다.</p> </div> <div class="listingblock"> <div class="title">초기화 프로세스 다이어그램</div> <div class="content"> <pre>@startuml start :Lancer `gradle init`; :Choisir "Gradle 플러그인"; :Choisir "코틀린" (langage); :Choisir "코틀린" (DSL); :Saisir nom, ID, et classe; :Projet généré; stop @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_2단계_생성된_구조_이해하기">2단계: 생성된 구조 이해하기</h2> <div class="sectionbody"> <div class="paragraph"> <p>어시스턴트는 루트 프로젝트와 플러그인 자체의 소스 코드를 분리하는 멀티 모듈 프로젝트 구조를 생성합니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">. ├── gradle/ │ └── wrapper/ │ ├── gradle-wrapper.jar │ └── gradle-wrapper.properties ├── gradlew ├── gradlew.bat ├── plugin/ │ ├── build.gradle.kts │ └── src/ │ ├── main/ │ │ └── kotlin/ │ │ └── com/cheroliv/SiteBakerPlugin.kt │ ├── test/ │ │ └── kotlin/ │ │ └── com/cheroliv/SiteBakerPluginTest.kt │ └── functionalTest/ │ └── kotlin/ │ └── com/cheroliv/SiteBakerPluginFunctionalTest.kt └── settings.gradle.kts</code></pre> </div> </div> <div class="sect2"> <h3 id="_주요_파일_및_폴더">주요 파일 및 폴더</h3> <div class="ulist"> <ul> <li> <p><code>settings.gradle.kts`이 파일은 루트에 위치하며 빌드에 포함된 모듈을 정의합니다. 여기서, 이는 하위 프로젝트를 포함합니다.`plugin</code>.</p> </li> </ul> </div> <div class="paragraph"> <p>[source,kotlin] ---- rootProject.name = "site-baker 포함("플러그인") (Empty output)</p> </div> <div class="listingblock"> <div class="content"> <pre></pre> </div> </div> </div> </div> </div> https://cheroliv.com/blog/2025/0088_environnement_plugin_gradle_post.html Mon, 22 Sep 2025 00:00:00 +0000 blog/2025/0088_environnement_plugin_gradle_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_소개">소개</a></li> <li><a href="#_1_jdk_gradle_엔진">1. JDK: Gradle 엔진</a> <ul class="sectlevel2"> <li><a href="#_어떤_버전을_선택해야_할까요">어떤 버전을 선택해야 할까요?</a></li> <li><a href="#_sdkman을_통한_설치_권장">SDKMAN!을 통한 설치 (권장)</a> <ul class="sectlevel3"> <li><a href="#_sdkman_설치"><strong>SDKMAN! 설치</strong></a></li> <li><a href="#_jdk_버전_설치">JDK 버전 설치</a></li> <li><a href="#_설치_확인">설치 확인</a></li> </ul> </li> </ul> </li> <li><a href="#_2_ide_intellij_idea">2. IDE : IntelliJ IDEA</a></li> <li><a href="#_3_gradle_빌드_도구">3. Gradle : 빌드 도구</a> <ul class="sectlevel2"> <li><a href="#_sdkman을_통한_설치">SDKMAN!을 통한 설치!</a> <ul class="sectlevel3"> <li><a href="#_gradle_설치">Gradle 설치</a></li> <li><a href="#_설치_확인_2">설치 확인</a></li> </ul> </li> </ul> </li> <li><a href="#_4_jbake_정적_사이트_생성기">4. JBake : 정적 사이트 생성기</a> <ul class="sectlevel2"> <li><a href="#_sdkman을_통한_설치_2">SDKMAN!을 통한 설치</a> <ul class="sectlevel3"> <li><a href="#_jbake_설치"><strong>JBake 설치</strong></a></li> <li><a href="#_설치_확인_3">설치 확인</a></li> </ul> </li> </ul> </li> <li><a href="#_5_gradle_wrapper_절대적인_모범_사례">5. Gradle Wrapper: 절대적인 모범 사례</a></li> <li><a href="#_6_docker와_portainer_재현_가능한_빌드_선택_사항">6. Docker와 Portainer : 재현 가능한 빌드 (선택 사항)</a> <ul class="sectlevel2"> <li><a href="#_docker_engine_설치">Docker Engine 설치</a> <ul class="sectlevel3"> <li><a href="#_docker을_공식_스크립트로_설치하기"><strong>Docker을 공식 스크립트로 설치하기 :</strong></a></li> <li><a href="#_docker_관리_sudo_없이_권장"><strong>Docker 관리 <code>sudo</code> 없이 (권장) :</strong></a></li> </ul> </li> <li><a href="#_portainer_gui로_docker_관리하기">Portainer (GUI)로 Docker 관리하기</a> <ul class="sectlevel3"> <li><a href="#_portainer_데이터용_볼륨을_생성하세요">Portainer 데이터용 볼륨을 생성하세요:</a></li> <li><a href="#_portainer_컨테이너_실행">Portainer 컨테이너 실행 :</a></li> </ul> </li> </ul> </li> <li><a href="#_결론">결론</a></li> </ul> </div> <div class="sect1"> <h2 id="_소개">소개</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">대상 고객 : Gradle 플러그인 개발에 도전하고자 하는 개발자.</div> <p>그레이들 플러그인을 효과적으로 개발하려면 잘 구성된 개발 환경이 필수적입니다. 좋은 설정은 시간을 절약해 주고, 불만을 줄이며, 빌드의 일관성을 보장합니다.</p> </div> <div class="olist arabic"> <div class="title">이 가이드는 네 가지 필수 기둥에 초점을 맞춥니다 :</div> <ol class="arabic"> <li> <p>Le <strong>JDK</strong>(Java Development Kit), Gradle과 JBake가 JVM에서 실행되기 때문에.</p> </li> <li> <p>Un <strong>통합 개발 환경</strong>현대적인 (IntelliJ IDEA) Kotlin과 Gradle에 대한 좋은 지원</p> </li> <li> <p><strong>그레이들</strong>스스로, 프로젝트를 초기화하기 위해</p> </li> <li> <p><strong>제이베이크</strong>, 우리 정적 사이트의 엔진.</p> </li> </ol> </div> <div class="listingblock"> <div class="title">개발 환경 구성 요소</div> <div class="content"> <pre>@startuml !theme plain node "개발자 기계" { component "JDK (JVM)" as JDK component "IntelliJ IDEA" as IDE component "Gradle (전역)" as Gradle component "JBake (글로벌)" as JBake IDE --> JDK : utilise Gradle --> JDK : utilise JBake --> JDK : utilise } @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_1_jdk_gradle_엔진">1. JDK: Gradle 엔진</h2> <div class="sectionbody"> <div class="paragraph"> <p>Gradle는 Java Virtual Machine (JVM)에서 실행되는 애플리케이션입니다. 따라서 JDK 설치는 절대적인 필수 조건입니다.</p> </div> <div class="sect2"> <h3 id="_어떤_버전을_선택해야_할까요">어떤 버전을 선택해야 할까요?</h3> <div class="paragraph"> <p>자바의 Long-Term Support (LTS) 버전을 사용하는 것이 권장됩니다. 현재로서는,<strong>JDK 17</strong> ou <strong>JDK 21</strong>훌륭한 선택입니다.</p> </div> </div> <div class="sect2"> <h3 id="_sdkman을_통한_설치_권장">SDKMAN!을 통한 설치 (권장)</h3> <div class="paragraph"> <p>SDKMAN! 은 Java와 Gradle을 포함한 많은 SDK의 버전을 관리하기에 훌륭한 도구입니다.</p> </div> <div class="sect3"> <h4 id="_sdkman_설치"><strong>SDKMAN! 설치</strong></h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">curl -s "https://get.sdkman.io" | bash source "$HOME/.sdkman/bin/sdkman-init.sh"</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_jdk_버전_설치">JDK 버전 설치</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Pour lister les versions de Java disponibles sdk list java # Pour installer Java 17 (par exemple, la distribution Temurin) sdk install java 17.0.8-tem</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_설치_확인">설치 확인</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">java -version</code></pre> </div> </div> <div class="paragraph"> <p>방금 설치한 버전이 표시되는 것을 보셔야 합니다.</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_2_ide_intellij_idea">2. IDE : IntelliJ IDEA</h2> <div class="sectionbody"> <div class="paragraph"> <p>Gradle 플러그인 개발에 Kotlin DSL을 사용할 때,<strong>인텔리J IDEA</strong>는 선호되는 도구입니다. 그의 Gradle 및 Kotlin과의 통합은 비교할 수 없습니다.</p> </div> <div class="ulist"> <ul> <li> <p><strong>Community Edition :</strong>무료이며 시작하기에 충분합니다.</p> </li> <li> <p><strong>얼티밋 에디션 :</strong>유료이며, 웹 및 데이터베이스 개발을 위한 고급 기능을 제공합니다.</p> </li> </ul> </div> <div class="paragraph"> <p>JetBrains 사이트에서 당신에게 맞는 버전을 다운로드하세요 : <a href="https://www.jetbrains.com/idea/download/" class="bare">https://www.jetbrains.com/idea/download/</a></p> </div> <div class="paragraph"> <p>IDE가 자동으로 파일을 감지합니다.<code>build.gradle.kts</code> et <code>settings.gradle.kts</code>, 강력한 자동 완성, 코드 내비게이션, 그리고 통합 디버깅 도구를 제공합니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_3_gradle_빌드_도구">3. Gradle : 빌드 도구</h2> <div class="sectionbody"> <div class="paragraph"> <p>각 프로젝트가 Gradle Wrapper를 통해 자체 Gradle 버전을 사용하더라도, 새 프로젝트 초기화와 같은 작업에는 전역 Gradle 설치를 해두는 것이 유용합니다 (<code>gradle init</code>)</p> </div> <div class="sect2"> <h3 id="_sdkman을_통한_설치">SDKMAN!을 통한 설치!</h3> <div class="paragraph"> <p>JDK와 마찬가지로, SDKMAN!은 Gradle 설치를 간소화합니다.</p> </div> <div class="sect3"> <h4 id="_gradle_설치">Gradle 설치</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sdk install gradle</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_설치_확인_2">설치 확인</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">gradle -v</code></pre> </div> </div> <div class="paragraph"> <p>이 명령은 사용되는 Gradle, Kotlin, Groovy 및 JDK의 버전을 표시합니다.</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_4_jbake_정적_사이트_생성기">4. JBake : 정적 사이트 생성기</h2> <div class="sectionbody"> <div class="paragraph"> <p>JBake는 우리가 소스 파일(예: 이 파일)을 정적 웹사이트로 변환하는 데 사용할 도구입니다. 로컬 설치를 갖는 것은 변경 사항을 미리 보는 데 편리합니다.</p> </div> <div class="sect2"> <h3 id="_sdkman을_통한_설치_2">SDKMAN!을 통한 설치</h3> <div class="paragraph"> <p>다른 도구들과 마찬가지로, SDKMAN!이 가장 간단한 방법입니다.</p> </div> <div class="sect3"> <h4 id="_jbake_설치"><strong>JBake 설치</strong></h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sdk install jbake</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_설치_확인_3">설치 확인</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">jbake -v</code></pre> </div> </div> <div class="paragraph"> <p>이 명령은 JBake 버전과 이를 사용하는 Java 환경 정보를 표시합니다.</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_5_gradle_wrapper_절대적인_모범_사례">5. Gradle Wrapper: 절대적인 모범 사례</h2> <div class="sectionbody"> <div class="paragraph"> <p>프로젝트가 생성된 후(다음 문서에서 다룰 내용과 같이), 더 이상 전역 명령어를 사용해서는 안 됩니다.<code>gradle</code>. 대신에, 당신은 그것을 사용할 것입니다.<strong>그레이들 래퍼</strong> (<code>./gradlew</code>), 프로젝트에 포함된 스크립트.</p> </div> <div class="paragraph"> <p>왜?</p> </div> <div class="ulist"> <ul> <li> <p><strong>재현성:</strong>Wrapper는 프로젝트에서 작업하는 모든 사람(CI/CD 서버 포함)이 정확히 라를 사용하도록 보장합니다.<strong>같은 버전의 Gradle</strong>, 이로 인해 다른 환경으로 인한 빌드 오류가 제거됩니다.</p> </li> <li> <p><strong>단순함 :</strong>프로젝트에 기여하기 위해 Gradle을 수동으로 설치할 필요가 없습니다.</p> </li> </ul> </div> <div class="paragraph"> <p>저장소를 클론하고 실행하기만 하면 됩니다.<code>./gradlew</code>.</p> </div> <div class="paragraph"> <p>일반적인 명령은 다음과 같이 보일 것입니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Ne pas faire : gradle build # À faire : ./gradlew build</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_6_docker와_portainer_재현_가능한_빌드_선택_사항">6. Docker와 Portainer : 재현 가능한 빌드 (선택 사항)</h2> <div class="sectionbody"> <div class="paragraph"> <p>플러그인을 작성하는 데 엄격히 필요한 것은 아니지만, Docker와 Portainer는 재현 가능한 빌드 생성을 크게 용이하게 하고 환경을 관리하는 데 도움을 주는 현대적인 DevOps 도구입니다.</p> </div> <div class="sect2"> <h3 id="_docker_engine_설치">Docker Engine 설치</h3> <div class="paragraph"> <p>Docker을 사용하면 애플리케이션과 그 종속성을 컨테이너에 패키징할 수 있습니다.</p> </div> <div class="sect3"> <h4 id="_docker을_공식_스크립트로_설치하기"><strong>Docker을 공식 스크립트로 설치하기 :</strong></h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_docker_관리_sudo_없이_권장"><strong>Docker 관리 <code>sudo</code> 없이 (권장) :</strong></h4> <div class="paragraph"> <p>사용자를 그룹에 추가하세요.<code>docker</code>.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo usod -aG docker $USER</code></pre> </div> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="Important"></i> </td> <td class="content"> </td> </tr> </table> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">docker run hello-world</code></pre> </div> </div> </div> </div> <div class="sect2"> <h3 id="_portainer_gui로_docker_관리하기">Portainer (GUI)로 Docker 관리하기</h3> <div class="paragraph"> <p>Portainer는 Docker 컨테이너를 관리하기 위한 가벼운 웹 인터페이스입니다.</p> </div> <div class="sect3"> <h4 id="_portainer_데이터용_볼륨을_생성하세요">Portainer 데이터용 볼륨을 생성하세요:</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">docker volume create portainer_data</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_portainer_컨테이너_실행">Portainer 컨테이너 실행 :</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:latest</code></pre> </div> </div> <div class="paragraph"> <p>이제 Portainer 인터페이스에 접근할 수 있습니다`https://localhost:9443`.</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_결론">결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>당신의 환경이 이제 준비되었습니다! JDK, 가장 적합한 IDE, Gradle 및 JBake가 있습니다. Docker을 추가하면 컨테이너화되고 재현 가능한 빌드를 만들 수 있도록 준비됩니다. 이 견고한 기반은 여러분이 핵심에 집중할 수 있게 해 줄 것입니다: 강력하고 유용한 플러그인 개발.</p> </div> <div class="paragraph"> <p>다음 기사에서는 명령을 사용할 것입니다.`gradle init`첫 번째 플러그인 프로젝트의 구조를 생성하기 위해</p> </div> </div> </div> https://cheroliv.com/blog/2025/0087_pypi_cicd_part_3_post.html Sat, 19 Jul 2025 00:00:00 +0000 blog/2025/0087_pypi_cicd_part_3_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_poetry와의_통합">Poetry와의 통합</a> <ul class="sectlevel2"> <li><a href="#_poetry_설치">Poetry 설치</a></li> <li><a href="#_프로젝트_초기화">프로젝트 초기화</a></li> <li><a href="#_의존성_추가_및_설치">의존성 추가 및 설치</a></li> <li><a href="#_poetry와_함께_게시">Poetry와 함께 게시</a></li> </ul> </li> <li><a href="#_도커를_사용한_재현_가능한_빌드">도커를 사용한 재현 가능한 빌드</a> <ul class="sectlevel2"> <li><a href="#_dockerfile_예시">Dockerfile 예시</a></li> <li><a href="#_github_actions_통합">GitHub Actions 통합</a></li> </ul> </li> <li><a href="#_조건부_게시">조건부 게시</a></li> <li><a href="#_renovate_및_dependabot을_사용한_의존성_자동화">Renovate 및 Dependabot을 사용한 의존성 자동화</a> <ul class="sectlevel2"> <li><a href="#_dependabot">Dependabot</a></li> <li><a href="#_리모델링하다">리모델링하다</a></li> </ul> </li> <li><a href="#_plantuml_다이어그램">PlantUML 다이어그램</a> <ul class="sectlevel2"> <li><a href="#_사용_사례_고급_cicd">사용 사례 – 고급 CI/CD</a></li> <li><a href="#_시퀀스_조건부_게시">시퀀스 – 조건부 게시</a></li> <li><a href="#_상태_cicd_파이프라인">상태 – CI/CD 파이프라인</a></li> <li><a href="#_배포_cicd_아키텍처">배포 – CI/CD 아키텍처</a></li> </ul> </li> <li><a href="#_결론">결론</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>이 시리즈의 처음 두 부분에서 우리는 : - 작동하는 CI/CD 파이프라인을 Python 애플리케이션용으로 GitHub Actions 및 PyPI를 이용해 구축했습니다. - 이 파이프라인을 다중 버전 테스트, Test PyPI를 통한 점진적 배포, 그리고 품질 및 보안 도구로 산업화했습니다.</p> </div> <div class="paragraph"> <p>이 세 번째 부분에서 우리는 갈 것입니다.<strong>PyPI에 단순한 게시를 넘어</strong>CI/CD 파이프라인을 완전히 강력하고 전문적으로 구축하기 위해 : - <strong>시</strong>현대적인 패키징과 최적화된 의존성 관리를 위해 - <strong>도커</strong>재현 가능하고 다중 플랫폼을 지원하는 빌드를 만들기 위해 - <strong>조건부 발행</strong>릴리스 후보와 같은 시나리오를 관리하기 위해 - <strong>자동화 도구</strong>(Renovate, Dependabot)를 사용해 파이프라인을 손쉽게 최신 상태로 유지하기</p> </div> </div> </div> <div class="sect1"> <h2 id="_poetry와의_통합">Poetry와의 통합</h2> <div class="sectionbody"> <div class="paragraph"> <p>Poetry는 기존 패키징 도구(setup.py, requirements.txt)를 대체하여 의존성 및 빌드 관리를 중앙 집중화하여`pyproject.toml`.</p> </div> <div class="sect2"> <h3 id="_poetry_설치">Poetry 설치</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-shell hljs" data-lang="shell"># Installer Poetry curl -sSL https://install.python-poetry.org | python3 - # Vérifier la version poetry --version</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_프로젝트_초기화">프로젝트 초기화</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-shell hljs" data-lang="shell"># Initialiser un nouveau projet avec Poetry poetry init # Suivre l'assistant pour renseigner : nom, version, description, licence, dépendances.</code></pre> </div> </div> <div class="paragraph"> <p>이는 파일을 생성합니다.<code>pyproject.toml</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-toml hljs" data-lang="toml">[tool.poetry] name = "playlist-downloader" version = "0.1.0" description = "CLI tool for managing YouTube playlists" authors = ["Christophe Hérolivier <cheroliv@example.com>"] [tool.poetry.dependencies] python = ">=3.8" typer = "^0.9.0" yt-dlp = "^2023.7.6" google-api-python-client = "^2.0.0" google-auth-oauthlib = "^1.0.0" [tool.poetry.group.dev.dependencies] pytest = "^7.0" mypy = "^1.0" bandit = "^1.7" safety = "^2.3" black = "^23.0" ruff = "^0.1"</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_의존성_추가_및_설치">의존성 추가 및 설치</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-shell hljs" data-lang="shell">poetry add typer yt-dlp google-api-python-client google-auth-oauthlib poetry add --group dev pytest mypy black bandit safety ruff</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_poetry와_함께_게시">Poetry와 함께 게시</h3> <div class="paragraph"> <p>Poetry 네이티브하게 출판을 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-shell hljs" data-lang="shell"># Publication sur Test PyPI poetry publish --build --repository test-pypi # Publication sur PyPI poetry publish --build</code></pre> </div> </div> <div class="paragraph"> <p>이 명령은 자동으로 에 있는 정보를 사용합니다`pyproject.toml`.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_도커를_사용한_재현_가능한_빌드">도커를 사용한 재현 가능한 빌드</h2> <div class="sectionbody"> <div class="paragraph"> <p>개발, CI/CD, 프로덕션에서 동일한 실행 환경을 보장하기 위해 Docker는 Poetry와 완벽하게 통합됩니다.</p> </div> <div class="sect2"> <h3 id="_dockerfile_예시">Dockerfile 예시</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-dockerfile hljs" data-lang="dockerfile">FROM python:3.11-slim WORKDIR /app COPY pyproject.toml poetry.lock ./ RUN pip install poetry RUN poetry install --no-root --only main COPY . . CMD ["poetry", "run", "python", "cli.py"]</code></pre> </div> </div> <div class="paragraph"> <p>이것은 보장합니다: - 동결된 파이썬 환경. - 잠긴 의존성들 via`poetry.lock`. - Docker를 지원하는 모든 시스템에서 실행 가능한 이미지.</p> </div> </div> <div class="sect2"> <h3 id="_github_actions_통합">GitHub Actions 통합</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">name: Docker Build on: push: branches: [main] jobs: build-docker: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Build Docker image run: docker build -t ghcr.io/${{ github.repository }}:latest . - name: Push Docker image run: docker push ghcr.io/${{ github.repository }}:latest</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_조건부_게시">조건부 게시</h2> <div class="sectionbody"> <div class="paragraph"> <p>전문적인 파이프라인에서는 특정 경우에만 게시할 수 있어야 합니다 : - Release candidates Test PyPI сторону - 안정적인 버전을 PyPI로. - 도커 빌드만 트리거됨`main`.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">- name: Publish to Test PyPI if: contains(github.ref, '-rc') run: poetry publish --build --repository test-pypi - name: Publish to PyPI if: startsWith(github.ref, 'refs/tags/v') run: poetry publish --build</code></pre> </div> </div> <div class="paragraph"> <p>이 접근법은 실수로 게시되는 것을 방지합니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_renovate_및_dependabot을_사용한_의존성_자동화">Renovate 및 Dependabot을 사용한 의존성 자동화</h2> <div class="sectionbody"> <div class="paragraph"> <p>의존성이 낡아지지 않도록 자동 업데이트 도구를 통합하세요.</p> </div> <div class="sect2"> <h3 id="_dependabot">Dependabot</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">version: 2 updates: - package-ecosystem: "pip" directory: "/" schedule: interval: "weekly" - package-ecosystem: "github-actions" directory: "/" schedule: interval: "weekly"</code></pre> </div> </div> <div class="paragraph"> <p>Dependabot는 매주 Python 및 GitHub Actions 의존성을 업데이트하기 위해 PR을 엽니다.</p> </div> </div> <div class="sect2"> <h3 id="_리모델링하다">리모델링하다</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{ "extends": ["config:base"], "packageRules": [ { "matchManagers": ["pip"], "groupName": "python-dependencies", "schedule": ["before 6am on monday"] } ] }</code></pre> </div> </div> <div class="paragraph"> <p>Renovate는 더 세밀한 제어를 제공합니다: 의존성 그룹화, 일정, 그리고 고급 규칙.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_plantuml_다이어그램">PlantUML 다이어그램</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_사용_사례_고급_cicd">사용 사례 – 고급 CI/CD</h3> <div class="listingblock"> <div class="content"> <pre>@startuml actor Developer actor GitHub as "GitHub Actions" actor PyPI actor DockerRegistry as "Docker 레지스트리" actor Automation as "Renovate/Dependabot" Developer --> (Push code) (Trigger CI) --> GitHub GitHub --> (Run Tests & Lint) GitHub --> (Build Docker Image) GitHub --> DockerRegistry GitHub --> (Publish to Test PyPI) GitHub --> (Promote to PyPI) Automation --> (Update Dependencies) @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_시퀀스_조건부_게시">시퀀스 – 조건부 게시</h3> <div class="listingblock"> <div class="content"> <pre>@startuml !theme vibrant left to right direction Developer -> GitHub: Push tag v1.2.3-rc GitHub -> CI: Run tests CI -> CD: Check release type CD -> Test PyPI: Publish RC Developer -> GitHub: Push tag v1.2.3 GitHub -> CD: Publish to PyPI CD -> Docker Registry: Push Docker image @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_상태_cicd_파이프라인">상태 – CI/CD 파이프라인</h3> <div class="listingblock"> <div class="content"> <pre>@startuml [*] --> Idle Idle --> CI_Running : push CI_Running --> CI_Success : tests ok CI_Running --> CI_Failed : tests fail CI_Success --> CD_Running : tag detected CD_Running --> CD_Success : publish ok CD_Running --> CD_Failed : error CD_Success --> [*] @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_배포_cicd_아키텍처">배포 – CI/CD 아키텍처</h3> <div class="listingblock"> <div class="content"> <pre>@startuml node "개발자 머신" { component "Git 클라이언트" } node "GitHub 작업" { component "CI 워크플로우" component "CD 워크플로우" } node "패키지 저장소" { artifact "테스트 PyPI" artifact "PyPI" artifact "도커 레지스트리" } "개발자 머신" --> "GitHub 작업" "GitHub 작업" --> "테스트 PyPI" "GitHub 작업" --> "PyPI" "GitHub 작업" --> "도커 레지스트리" @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_결론">결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 세 번째 부분에서 우리는 다음과 같이 보았습니다: - Poetry를 활용한 Python 패키징 현대화 Docker을 통해 재현 가능한 빌드를 보장한다. - 조건부 게시물을 설정하세요. - 자동화 의존성 업데이트.</p> </div> <div class="paragraph"> <p>이제 CI/CD 파이프라인을 보유하고 있습니다.<strong>완전한, 산업화된, 그리고 안전한</strong>, 귀하의 프로젝트와 함께 발전할 준비가 된</p> </div> </div> </div> https://cheroliv.com/blog/2025/0086_pypi_cicd_part_2_post.html Fri, 18 Jul 2025 00:00:00 +0000 blog/2025/0086_pypi_cicd_part_2_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_소개">소개</a></li> <li><a href="#_cicd_파이프라인_아키텍처">CI/CD 파이프라인 아키텍처</a></li> <li><a href="#_프로젝트_구조">프로젝트 구조</a></li> <li><a href="#_pyproject_toml을_사용한_패키지_구성">pyproject.toml을 사용한 패키지 구성</a></li> <li><a href="#_cicd_워크플로_테스트_및_품질">CI/CD 워크플로 - 테스트 및 품질</a></li> <li><a href="#_릴리스_및_배포_워크플로우">릴리스 및 배포 워크플로우</a></li> <li><a href="#_아키텍처_다이어그램">아키텍처 다이어그램</a> <ul class="sectlevel2"> <li><a href="#_시퀀스_다이어그램_릴리스_프로세스">시퀀스 다이어그램 - 릴리스 프로세스</a></li> <li><a href="#_상태_다이어그램_패키지_생명주기">상태 다이어그램 - 패키지 생명주기</a></li> <li><a href="#_배포_다이어그램_cicd_인프라스트럭처">배포 다이어그램 - CI/CD 인프라스트럭처</a></li> </ul> </li> <li><a href="#_파이프라인_객체_및_모델">파이프라인 객체 및 모델</a> <ul class="sectlevel2"> <li><a href="#_클래스_다이어그램_cicd_모델">클래스 다이어그램 - CI/CD 모델</a></li> </ul> </li> <li><a href="#_시크릿_구성">시크릿 구성</a> <ul class="sectlevel2"> <li><a href="#_github_actions_시크릿">GitHub Actions 시크릿</a></li> <li><a href="#_pypi_토큰_생성">PyPI 토큰 생성</a></li> </ul> </li> <li><a href="#_로컬_개발_스크립트">로컬 개발 스크립트</a> <ul class="sectlevel2"> <li><a href="#_메이크파일">메이크파일</a></li> <li><a href="#_버전_스크립트">버전 스크립트</a></li> </ul> </li> <li><a href="#_모범_사례_및_권고안">모범 사례 및 권고안</a> <ul class="sectlevel2"> <li><a href="#_시맨틱_버저닝">시맨틱 버저닝</a></li> <li><a href="#_전략_브랜칭">전략 브랜칭</a></li> <li><a href="#_테스트_및_커버리지">테스트 및 커버리지</a></li> <li><a href="#_안전">안전</a></li> </ul> </li> <li><a href="#_모니터링_및_관찰_가능성">모니터링 및 관찰 가능성</a> <ul class="sectlevel2"> <li><a href="#_파이프라인_메트릭스">파이프라인 메트릭스</a></li> <li><a href="#_알림">알림</a></li> </ul> </li> <li><a href="#_결론">결론</a></li> <li><a href="#_보충_자료">보충 자료</a></li> </ul> </div> <div class="sect1"> <h2 id="_소개">소개</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">목표 : 간단한 파이프라인을 현대적인 포장 및 소프트웨어 엔지니어링 표준을 준수하는 견고한 산업용 파이프라인으로 변환합니다.</div> <p>이 시리즈의 첫 번째 부분에서 우리는 Python 패키지를 PyPI에 배포하고 테스트를 자동화하기 위해 간단하면서도 효과적인 CI/CD 파이프라인을 구축했습니다.</p> </div> <div class="paragraph"> <p>이제 이 파이프라인을 전문화할 시간입니다. 이 두 번째 부분에서, 우리는 :</p> </div> <div class="ulist"> <ul> <li> <p>현대 표준인 pyproject.toml로 마이그레이션,</p> </li> <li> <p>품질 및 안전 도구 추가 (Black, Mypy, Bandit, Safety),</p> </li> <li> <p>멀티버전 테스트를 설정,</p> </li> <li> <p>Test PyPI를 통해 점진적 배포를 통합하는</p> </li> <li> <p>버전 관리를 자동화하고 파이프라인 모니터링을 개선하세요.</p> </li> </ul> </div> <div class="paragraph"> <p>기능적인 파이프라인에서 전문적인 CI/CD 인프라로 전환할 준비를 하세요.</p> </div> <div class="paragraph"> <p>파이썬 애플리케이션을 PyPI에 배포하려면 테스트, 빌드, 패키지 출시를 자동화하는 강력한 CI/CD 파이프라인이 필요합니다. 이 문서는 Python CLI 애플리케이션을 위한 GitHub Actions를 사용한 완전한 파이프라인 구축을 자세히 설명하며, 현대 파이썬 생태계의 모범 사례를 기반으로 합니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_cicd_파이프라인_아키텍처">CI/CD 파이프라인 아키텍처</h2> <div class="sectionbody"> <div class="paragraph"> <p>우리가 구축할 파이프라인은 여러 단계로 구성된 접근 방식을 따릅니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml !theme plain title 파이썬 CI/CD 파이프라인 PyPI로 skinparam backgroundColor #f8f9fa skinparam componentStyle rectangle rectangle "개발자" as dev rectangle "GitHub 저장소" as repo { rectangle ".github/workflows/" as workflows rectangle "시험/" as tests rectangle "setup.py / pyproject.toml" as setup rectangle "requirements.txt" as req } rectangle "GitHub 액션" as actions { rectangle "테스트 러너" as test_runner rectangle "빌드" as build rectangle "보안 스캔" as security rectangle "품질 검사" as quality } rectangle "PyPI" as pypi { rectangle "테스트 PyPI" as test_pypi rectangle "프로덕션 PyPI" as prod_pypi } rectangle "사용자들" as users dev --> repo : push/PR repo --> actions : trigger workflow actions --> test_runner : run tests actions --> security : security checks actions --> quality : code quality actions --> build : build package build --> test_pypi : deploy (pre-release) build --> prod_pypi : deploy (release) prod_pypi --> users : install package @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_프로젝트_구조">프로젝트 구조</h2> <div class="sectionbody"> <div class="paragraph"> <p>배포 준비가 된 Python CLI 애플리케이션은 표준화된 구조를 따라야 합니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">playlist-downloader/ ├── .github/ │ └── workflows/ │ ├── ci.yml │ ├── release.yml │ └── security.yml ├── src/ │ └── playlist_downloader/ │ ├── __init__.py │ ├── cli.py │ ├── core/ │ └── adapters/ ├── tests/ │ ├── unit/ │ ├── integration/ │ └── conftest.py ├── docs/ ├── pyproject.toml ├── requirements.txt ├── requirements-dev.txt ├── MANIFEST.in ├── README.md ├── LICENSE └── CHANGELOG.md</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_pyproject_toml을_사용한_패키지_구성">pyproject.toml을 사용한 패키지 구성</h2> <div class="sectionbody"> <div class="paragraph"> <p>파일`pyproject.toml`는 Python 패키지를 구성하는 현대적인 표준입니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-toml hljs" data-lang="toml">[build-system] requires = ["setuptools>=45", "wheel", "setuptools_scm>=6.2"] build-backend = "setuptools.build_meta" [project] name = "playlist-downloader" authors = [ {name = "Christophe Hérolivier", email = "cheroliv@example.com"}, ] description = "CLI tool for YouTube playlist management" readme = "README.md" requires-python = ">=3.8" keywords = ["youtube", "playlist", "cli", "downloader"] license = {text = "MIT"} classifiers = [ "Development Status :: 4 - Beta", "Environment :: Console", "Intended Audience :: End Users/Desktop", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Topic :: Multimedia :: Sound/Audio", "Topic :: Utilities", ] dependencies = [ "typer>=0.9.0", "yt-dlp>=2023.7.6", "google-api-python-client>=2.0.0", "google-auth-oauthlib>=1.0.0", "pyyaml>=6.0", "rich>=13.0.0", ] dynamic = ["version"] [project.optional-dependencies] dev = [ "pytest>=7.0.0", "pytest-cov>=4.0.0", "pytest-mock>=3.10.0", "black>=23.0.0", "flake8>=6.0.0", "mypy>=1.0.0", "pre-commit>=3.0.0", "tox>=4.0.0", ] test = [ "pytest>=7.0.0", "pytest-cov>=4.0.0", "pytest-mock>=3.10.0", ] [project.urls] Homepage = "https://github.com/cheroliv/playlist-downloader" Documentation = "https://github.com/cheroliv/playlist-downloader#readme" Repository = "https://github.com/cheroliv/playlist-downloader.git" "Bug Tracker" = "https://github.com/cheroliv/playlist-downloader/issues" [project.scripts] playlist-downloader = "playlist_downloader.cli:main" [tool.setuptools_scm] write_to = "src/playlist_downloader/_version.py" [tool.setuptools.packages.find] where = ["src"] [tool.pytest.ini_options] testpaths = ["tests"] python_files = ["test_*.py"] python_classes = ["Test*"] python_functions = ["test_*"] addopts = [ "--cov=src/playlist_downloader", "--cov-report=html", "--cov-report=term-missing", "--cov-fail-under=85", ] [tool.black] line-length = 88 target-version = ['py38'] include = '\.pyi?$' extend-exclude = ''' /( \.eggs | \.git | \.hg | \.mypy_cache | \.tox | \.venv | _build | buck-out | build | dist )/ ''' [tool.mypy] python_version = "3.8" warn_return_any = true warn_unused_configs = true disallow_untyped_defs = true disallow_incomplete_defs = true check_untyped_defs = true disallow_untyped_decorators = true no_implicit_optional = true warn_redundant_casts = true warn_unused_ignores = true warn_no_return = true warn_unreachable = true strict_equality = true [[tool.mypy.overrides]] module = [ "yt_dlp.*", "googleapiclient.*", "google_auth_oauthlib.*", ] ignore_missing_imports = true</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_cicd_워크플로_테스트_및_품질">CI/CD 워크플로 - 테스트 및 품질</h2> <div class="sectionbody"> <div class="paragraph"> <p>주요 워크플로 (<code>ci.yml</code>) 테스트를 여러 버전에서 Python에서 실행합니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">name: CI on: push: branches: [ main, develop ] pull_request: branches: [ main ] jobs: test: runs-on: ubuntu-latest strategy: matrix: python-version: ["3.8", "3.9", "3.10", "3.11"] steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Set up Python ${{ matrix.python-version }} uses: actions/setup-python@v4 with: python-version: ${{ matrix.python-version }} - name: Cache dependencies uses: actions/cache@v3 with: path: | ~/.cache/pip ~/.cache/pre-commit key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt') }} restore-keys: | ${{ runner.os }}-pip- - name: Install dependencies run: | python -m pip install --upgrade pip pip install -e ".[dev]" - name: Lint with flake8 run: | flake8 src tests --count --select=E9,F63,F7,F82 --show-source --statistics flake8 src tests --count --exit-zero --max-complexity=10 --max-line-length=88 --statistics - name: Check code formatting with Black run: black --check src tests - name: Type checking with mypy run: mypy src - name: Run tests with pytest run: | pytest tests/ -v --cov=src/playlist_downloader \ --cov-report=xml --cov-report=term-missing - name: Upload coverage to Codecov uses: codecov/codecov-action@v3 if: matrix.python-version == '3.11' with: file: ./coverage.xml flags: unittests name: codecov-umbrella security: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v4 with: python-version: "3.11" - name: Install dependencies run: | python -m pip install --upgrade pip pip install bandit[toml] safety - name: Run security checks with bandit run: bandit -r src/ -f json -o bandit-report.json - name: Check dependencies with safety run: safety check --json --output safety-report.json - name: Upload security reports uses: actions/upload-artifact@v3 if: always() with: name: security-reports path: | bandit-report.json safety-report.json build: needs: [test, security] runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Set up Python uses: actions/setup-python@v4 with: python-version: "3.11" - name: Install build dependencies run: | python -m pip install --upgrade pip pip install build twine - name: Build package run: python -m build - name: Check package with twine run: twine check dist/* - name: Upload build artifacts uses: actions/upload-artifact@v3 with: name: dist path: dist/</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_릴리스_및_배포_워크플로우">릴리스 및 배포 워크플로우</h2> <div class="sectionbody"> <div class="paragraph"> <p>릴리스 워크플로우 (<code>release.yml</code>) 자동 PyPI 배포를 관리 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">name: Release on: push: tags: - 'v*.*.*' workflow_dispatch: inputs: environment: description: 'Deployment environment' required: true default: 'test' type: choice options: - test - production env: PYTHON_VERSION: "3.11" jobs: release: runs-on: ubuntu-latest environment: name: ${{ github.event.inputs.environment || (startsWith(github.ref, 'refs/tags/') && 'production' || 'test') }} steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Set up Python uses: actions/setup-python@v4 with: python-version: ${{ env.PYTHON_VERSION }} - name: Install dependencies run: | python -m pip install --upgrade pip pip install build twine - name: Build package run: python -m build - name: Check package run: twine check dist/* - name: Publish to Test PyPI if: github.event.inputs.environment == 'test' || (startsWith(github.ref, 'refs/tags/') && contains(github.ref, 'rc')) env: TWINE_USERNAME: __token__ TWINE_PASSWORD: ${{ secrets.TEST_PYPI_API_TOKEN }} run: | twine upload --repository testpypi dist/* - name: Publish to PyPI if: github.event.inputs.environment == 'production' || (startsWith(github.ref, 'refs/tags/') && !contains(github.ref, 'rc')) env: TWINE_USERNAME: __token__ TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} run: | twine upload dist/* - name: Create GitHub Release if: startsWith(github.ref, 'refs/tags/') uses: actions/create-release@v1 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: tag_name: ${{ github.ref }} release_name: Release ${{ github.ref }} draft: false prerelease: ${{ contains(github.ref, 'rc') }} post-release: needs: release runs-on: ubuntu-latest if: startsWith(github.ref, 'refs/tags/') steps: - uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v4 with: python-version: ${{ env.PYTHON_VERSION }} - name: Test installation from PyPI run: | sleep 60 # Attendre la propagation sur PyPI pip install playlist-downloader playlist-downloader --version - name: Update documentation run: | # Script pour mettre à jour la documentation echo "Documentation updated for version ${GITHUB_REF#refs/tags/}"</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_아키텍처_다이어그램">아키텍처 다이어그램</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_시퀀스_다이어그램_릴리스_프로세스">시퀀스 다이어그램 - 릴리스 프로세스</h3> <div class="listingblock"> <div class="content"> <pre>@startuml !theme plain title PyPI로의 릴리즈 시퀀스 actor Developer as dev participant "GitHub" as gh participant "GitHub Actions" as ga participant "테스트 PyPI" as tpypi participant "PyPI" as pypi participant "사용자" as users dev -> gh : git push --tags v1.2.3 gh -> ga : trigger release workflow ga -> ga : checkout code ga -> ga : setup Python environment ga -> ga : install dependencies ga -> ga : run tests ga -> ga : build package (wheel + sdist) ga -> ga : check package with twine alt Pre-release (rc tag) ga -> tpypi : upload to Test PyPI tpypi -> ga : confirm upload else Stable release ga -> pypi : upload to PyPI pypi -> ga : confirm upload end ga -> gh : create GitHub release ga -> ga : test installation from PyPI users -> pypi : pip install playlist-downloader pypi -> users : download package @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_상태_다이어그램_패키지_생명주기">상태 다이어그램 - 패키지 생명주기</h3> <div class="listingblock"> <div class="content"> <pre>@startuml !theme plain title Python 패키지 상태 [*] --> Development Development --> Testing : commit/PR Testing --> Development : tests fail Testing --> Built : tests pass Built --> TestPyPI : pre-release tag Built --> PyPI : stable tag TestPyPI --> PyPI : validation OK PyPI --> Published Published --> [*] state Development { [*] --> Coding Coding --> LocalTesting LocalTesting --> Coding : fix issues LocalTesting --> ReadyForCI : all tests pass } state Testing { [*] --> CITests CITests --> SecurityScan SecurityScan --> QualityCheck QualityCheck --> BuildValidation } @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_배포_다이어그램_cicd_인프라스트럭처">배포 다이어그램 - CI/CD 인프라스트럭처</h3> <div class="listingblock"> <div class="content"> <pre>@startuml !theme plain title 배포 인프라스트럭처 node "깃허브" { component "저장소" as repo component "액션 러너" as runner component "비밀 저장소" as secrets } node "PyPI 인프라" { component "PyPI" as pypi component "테스트 PyPI" as testpypi database "패키지 인덱스" as index } node "개발자 머신" { component "Git 클라이언트" as git component "파이썬 환경" as python component "통합 개발 환경" as ide } node "사용자 환경" { component "피프" as pip_client component "Python 런타임" as py_runtime } git --> repo : push code/tags repo --> runner : trigger workflows runner --> secrets : read API tokens runner --> testpypi : upload pre-release runner --> pypi : upload release pypi --> index : store package pip_client --> pypi : download package py_runtime <-- pip_client : install package @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_파이프라인_객체_및_모델">파이프라인 객체 및 모델</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_클래스_다이어그램_cicd_모델">클래스 다이어그램 - CI/CD 모델</h3> <div class="listingblock"> <div class="content"> <pre>@startuml !theme plain title CI/CD 파이프라인 템플릿 class PipelineConfig { +python_versions: List[str] +test_environments: List[str] +security_checks: bool +coverage_threshold: float +validate() } class BuildArtifact { +name: str +version: str +wheel_path: str +sdist_path: str +checksums: Dict[str, str] +validate_integrity() } class TestResult { +test_suite: str +python_version: str +passed: int +failed: int +coverage: float +duration: float +is_success(): bool } class SecurityReport { +bandit_issues: List[Issue] +safety_vulnerabilities: List[Vulnerability] +severity_level: str +is_secure(): bool } class DeploymentTarget { +name: str +url: str +api_token: str +environment: str +deploy(artifact: BuildArtifact) } class ReleaseManager { +version: str +changelog: str +artifacts: List[BuildArtifact] +test_results: List[TestResult] +security_report: SecurityReport +deploy_to_test() +deploy_to_production() +create_github_release() } PipelineConfig ||--o{ TestResult ReleaseManager *-- BuildArtifact ReleaseManager *-- SecurityReport ReleaseManager o-- DeploymentTarget DeploymentTarget ..> BuildArtifact : uses @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_시크릿_구성">시크릿 구성</h2> <div class="sectionbody"> <div class="paragraph"> <p>파이프라인이 작동하려면 GitHub에 다음 비밀을 구성해야 합니다:</p> </div> <div class="sect2"> <h3 id="_github_actions_시크릿">GitHub Actions 시크릿</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Dans Settings > Secrets and variables > Actions # Token PyPI pour la production PYPI_API_TOKEN=pypi-... # Token Test PyPI pour les pré-releases TEST_PYPI_API_TOKEN=pypi-... # Token GitHub pour créer les releases GITHUB_TOKEN=(automatiquement fourni) # Token Codecov (optionnel) CODECOV_TOKEN=...</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_pypi_토큰_생성">PyPI 토큰 생성</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># 1. Créer un compte sur PyPI et Test PyPI # 2. Aller dans Account Settings > API tokens # 3. Créer un token avec scope "Entire account" ou spécifique au projet # 4. Format du token : pypi-AgEIcHlwaS5vcmc...</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_로컬_개발_스크립트">로컬 개발 스크립트</h2> <div class="sectionbody"> <div class="paragraph"> <p>개발을 용이하게 하기 위해 유용한 스크립트를 만드세요 :</p> </div> <div class="sect2"> <h3 id="_메이크파일">메이크파일</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-makefile hljs" data-lang="makefile">.PHONY: install test lint format security build clean release-test release-prod install: pip install -e ".[dev]" test: pytest tests/ -v --cov=src/playlist_downloader lint: flake8 src tests mypy src format: black src tests security: bandit -r src/ safety check build: python -m build twine check dist/* clean: rm -rf build/ dist/ *.egg-info/ find . -type d -name __pycache__ -delete find . -name "*.pyc" -delete release-test: clean build twine upload --repository testpypi dist/* release-prod: clean build twine upload dist/* pre-commit: format lint test security @echo "✅ Prêt pour commit"</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_버전_스크립트">버전 스크립트</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-python hljs" data-lang="python">#!/usr/bin/env python3 """Script pour gérer les versions du projet.""" import sys import subprocess from pathlib import Path def get_current_version(): """Récupère la version actuelle depuis git.""" try: result = subprocess.run( ["git", "describe", "--tags", "--abbrev=0"], capture_output=True, text=True, check=True ) return result.stdout.strip() except subprocess.CalledProcessError: return "0.0.0" def create_version_tag(version, message=None): """Crée un tag de version.""" if not version.startswith('v'): version = f'v{version}' tag_message = message or f"Release {version}" subprocess.run(["git", "tag", "-a", version, "-m", tag_message], check=True) print(f"✅ Tag {version} créé") # Push le tag subprocess.run(["git", "push", "origin", version], check=True) print(f"✅ Tag {version} poussé vers origin") if __name__ == "__main__": if len(sys.argv) < 2: current = get_current_version() print(f"Version actuelle: {current}") print("Usage: python version.py <new_version> [message]") sys.exit(1) new_version = sys.argv[1] message = sys.argv[2] if len(sys.argv) > 2 else None create_version_tag(new_version, message)</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_모범_사례_및_권고안">모범 사례 및 권고안</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_시맨틱_버저닝">시맨틱 버저닝</h3> <div class="paragraph"> <p>의미론적 버전 관리(SemVer)를 사용하세요:</p> </div> <div class="ulist"> <ul> <li> <p><code>MAJOR.MINOR.PATCH</code> (ex: 1.2.3)</p> </li> <li> <p><code>MAJOR</code>: 호환되지 않는 변경</p> </li> <li> <p><code>MINOR</code>: 새로운 호환 가능한 기능</p> </li> <li> <p><code>PATCH</code>: 호환 가능한 버그 수정</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_전략_브랜칭">전략 브랜칭</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">main ──●──●──●──●──●────●── (releases stables) / / / develop ──●──●──●──●──●──●──●──●── (développement) / / / feature/xxx ●──●──●──●──●──/ (fonctionnalités)</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_테스트_및_커버리지">테스트 및 커버리지</h3> <div class="ulist"> <ul> <li> <p>최소 코드 커버리지: 85%</p> </li> <li> <p>비즈니스 로직을 위한 단위 테스트</p> </li> <li> <p>어댑터를 위한 통합 테스트</p> </li> <li> <p>CLI에 대한 엔드 투 엔드 테스트</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_안전">안전</h3> <div class="ulist"> <ul> <li> <p>자동 의존성 스캔 (Safety)</p> </li> <li> <p>정적 코드 분석 (Bandit)</p> </li> <li> <p>비밀 assoluto 코드에</p> </li> <li> <p>특정 PyPI 토큰 사용</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_모니터링_및_관찰_가능성">모니터링 및 관찰 가능성</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_파이프라인_메트릭스">파이프라인 메트릭스</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml"># .github/workflows/metrics.yml name: Pipeline Metrics on: workflow_run: workflows: ["CI", "Release"] types: [completed] jobs: metrics: runs-on: ubuntu-latest steps: - name: Collect metrics run: | echo "Pipeline: ${{ github.event.workflow_run.name }}" echo "Status: ${{ github.event.workflow_run.conclusion }}" echo "Duration: ${{ github.event.workflow_run.updated_at - github.event.workflow_run.created_at }}" # Envoyer vers système de monitoring</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_알림">알림</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml"># Ajout dans les workflows pour notifications - name: Notify on failure if: failure() uses: 8398a7/action-slack@v3 with: status: failure text: "❌ Pipeline failed for ${{ github.repository }}" env: SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_결론">결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 완전한 Python용 CI/CD 파이프라인은 다음을 제공합니다:</p> </div> <div class="ulist"> <ul> <li> <p><strong>완전 자동화</strong>: 코드 검증에서 게시까지</p> </li> <li> <p><strong>보안</strong>자동 스캔 및 보안 비밀 관리</p> </li> <li> <p><strong>품질</strong>: 멀티 버전 테스트, 린팅 및 코드 커버리지</p> </li> <li> <p><strong>신뢰성</strong>: Test PyPI를 통한 점진적 배포</p> </li> <li> <p><strong>추적성</strong>: 아티팩트, 보고서 및 GitHub 릴리스</p> </li> </ul> </div> <div class="paragraph"> <p>이러한 관행을 채택하면 Python CLI 애플리케이션에 대한 견고하고 전문적인 배포 프로세스가 보장되어 프로젝트의 유지 관리와 장기적인 발전을 용이하게 합니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_보충_자료">보충 자료</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://packaging.python.org/">Python 패키징 사용자 가이드</a></p> </li> <li> <p><a href="https://docs.github.com/en/actions">GitHub Actions 문서</a></p> </li> <li> <p><a href="https://pypi.org/help/">PyPI 도움말 문서</a></p> </li> <li> <p><a href="https://semver.org/">의미적 버전 관리 사양</a></p> </li> <li> <p><a href="https://keepachangelog.com/">변경 로그를 유지해</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2025/0085_pypi_cicd_part_1_post.html Thu, 17 Jul 2025 00:00:00 +0000 blog/2025/0085_pypi_cicd_part_1_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_소개">소개</a></li> <li><a href="#_파이프라인_아키텍처">파이프라인 아키텍처</a></li> <li><a href="#_연속_통합ci_파이프라인_구성">연속 통합(CI) 파이프라인 구성</a> <ul class="sectlevel2"> <li><a href="#_ci_워크플로우_구조">CI 워크플로우 구조</a></li> <li><a href="#_ci_단계_분석">CI 단계 분석</a> <ul class="sectlevel3"> <li><a href="#_1_트리거_on">1. 트리거 (<code>on</code>)</a></li> </ul> </li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_소개">소개</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">목표 : 독자가 최소한이지만 기능적인 파이썬 애플리케이션용 CI/CD 파이프라인을 설정하고 PyPI에 자동 배포하도록 안내합니다.</div> <p>개발 프로세스의 자동화는 현대 프로젝트에서 필수적이 되었습니다. 잘 설계된 CI/CD 파이프라인은 개발 주기 초기에 회귀를 감지하는 것뿐만 아니라 배포 프로세스를 완전히 자동화할 수 있습니다.</p> </div> <div class="paragraph"> <p>이 문서에서는 GitHub Actions를 사용하여 Python 애플리케이션에 대한 완전한 CI/CD 파이프라인을 구축하는 방법을 살펴보겠습니다. 여기서 CI는 지속적 통합, CD는 지속적 배포를 의미하며, PyPI에 배포하는 과정까지 다룹니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_파이프라인_아키텍처">파이프라인 아키텍처</h2> <div class="sectionbody"> <div class="paragraph"> <p>우리의 파이프라인은 두 개의 서로 다른 워크플로우로 구성됩니다 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>CI 파이프라인</strong>각 푸시 및 pull request마다 실행됩니다</p> </li> <li> <p><strong>CD 파이프라인</strong>: GitHub 릴리스 중에만 트리거됨</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre>@startuml !theme plain package "GitHub 저장소" { [Source Code] as source [GitHub Actions] as actions } package "CI 파이프라인" { [Checkout] as checkout_ci [Setup Python] as python_ci [Install Dependencies] as deps_ci [Linting (Ruff)] as lint [Unit Tests] as tests } package "CD 파이프라인" { [Checkout] as checkout_cd [Setup Python] as python_cd [Build Package] as build [Publish to PyPI] as pypi } source --> actions : Push/PR actions --> checkout_ci checkout_ci --> python_ci python_ci --> deps_ci deps_ci --> lint lint --> tests source --> actions : Release actions --> checkout_cd : On Release checkout_cd --> python_cd python_cd --> build build --> pypi @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_연속_통합ci_파이프라인_구성">연속 통합(CI) 파이프라인 구성</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_ci_워크플로우_구조">CI 워크플로우 구조</h3> <div class="paragraph"> <p>CI 워크플로우는 코드의 각 기여를 검증하도록 설계되었습니다. 다음은 전체 구성 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">name: CI/CD Pipeline on: push: branches: - main pull_request: branches: - main jobs: build: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 with: python-version: '3.x' - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt pip install ruff pytest pytest-mock - name: Run Linting (Ruff) run: ruff check . - name: Run Tests (Pytest) run: pytest</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_ci_단계_분석">CI 단계 분석</h3> <div class="sect3"> <h4 id="_1_트리거_on">1. 트리거 (<code>on</code>)</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">---- ---- on: push: branches: - main pull_request: branches: - main ---- 파이프라인이 다음에 따라 트리거됩니다: - 브랜치에 푸시할 때마다`main` - 각 pull request에 대해`main` 이 접근 방식은 메인 코드가 안정적으로 유지되도록 하고 모든 기여가 통합되기 전에 검증되도록 보장합니다. ==== 2. 실행 환경 ---- runs-on: ubuntu-latest Ubuntu Latest는 대부분의 Python 프로젝트에 성능, 비용, 호환성 측면에서 좋은 균형을 제공합니다. ==== 3. 코드 체크아웃 ```yaml ---- ---- - name: Checkout code uses: actions/checkout@v4 ---- 행동`checkout@v4`저장소의 소스 코드를 가져옵니다. v4 버전은 성능과 보안 개선을 제공합니다. ==== 4. 파이썬 구성 ---- - name: Set up Python uses: actions/setup-python@v5 with: python-version: '3.x' 사용`'3.x'`자동으로 최신 안정 버전의 Python 3을 사용하게 하여 유지 관리를 간소화합니다. ==== 5. 의존성 설치 ```yaml ---- ---- - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt pip install ruff pytest pytest-mock ---- 이 단계: - pip을 최신 버전으로 업데이트합니다 - 프로젝트 의존성을 설치합니다. - 개발 도구(린팅 및 테스트)를 추가합니다. ==== 6. Ruff로 린팅 ---- - name: Run Linting (Ruff) run: ruff check . **러프**은 초고속 파이썬 린터로, Rust로 작성되었습니다. 이는 여러 도구(Flake8, Black, isort)의 기능을 하나의 성능 좋은 도구로 결합합니다. ==== 7. 테스트 실행 ```yaml ---- ---- - name: Run Tests (Pytest) run: pytest ---- Pytest는 테스트 스위트 전체를 실행하여 변경 사항이 회귀를 일으키지 않도록 보장합니다. == 배포 파이프라인 구성(CD) === CD 워크플로우 구조 CD 워크플로우는 GitHub 릴리스에서만 트리거되고 PyPI에 게시를 자동화합니다: [source,yaml] ---- name: Publish to PyPI on: release: types: - published jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 with: python-version: '3.x' - name: Install dependencies run: | python -m pip install --upgrade pip pip install setuptools wheel twine - name: Build and publish env: TWINE_USERNAME: __token__ TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} run: | python setup.py sdist bdist_wheel twine upload dist/* ---- === CD 단계 분석 ==== 트리거 출시 ---- on: release: types: - published CD 파이프라인은 GitHub 릴리스가 게시될 때만 트리거됩니다. 이 접근 방식은 배포에 대한 정확한 제어를 보장합니다. ==== 2. 빌드 도구 설치 ```yaml ---- ---- pip install setuptools wheel twine ---- - **setuptools**: 파이썬 패키징 도구 - **바퀴**: 현대적인 Python 배포 형식 - **끈**PyPI에 업로드하는 보안 도구 ==== 3. 인증 구성 ---- env: TWINE_USERNAME: __token__ TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} 인증은 GitHub 비밀에 저장된 PyPI API 토큰을 사용하며, 이는 기존 자격 증명보다 더 안전합니다. ==== 4. 빌드 및 배포 ```yaml ---- ---- run: | python setup.py sdist bdist_wheel twine upload dist/* ---- - `sdist`: 소스 배포본을 생성합니다. - `bdist_wheel`: 휠(바이너리 배포)를 생성합니다 - `twine upload`PyPI에 배포를 게시합니다 == 파이썬 패키지 구성 === setup.py의 구조 파이프라인이 작동하려면 프로젝트에 파일을 포함해야 합니다.`setup.py`: [source,python] ---- from setuptools import setup, find_packages with open("README.adoc", "r", encoding="utf-8") as fh: long_description = fh.read() setup( name="playlist-downloader", version="1.0.0", author="Votre Nom", author_email="votre.email@example.com", description="CLI tool for managing YouTube playlists", long_description=long_description, long_description_content_type="text/plain", url="https://github.com/cheroliv/playlist-downloader", packages=find_packages(), classifiers=[ "Development Status :: 4 - Beta", "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", ], python_requires=">=3.8", install_requires=[ "typer>=0.9.0", "yt-dlp>=2023.1.6", "google-api-python-client>=2.70.0", "google-auth-oauthlib>=0.7.1", "pymonad>=2.4.0", "pyyaml>=6.0", ], entry_points={ "console_scripts": [ "playlist-downloader=cli:app", ], }, ) ---- === setup.py의 핵심 포인트 1. **메타데이터**: 이름, 버전, 작가, 설명 2. **의존성**필요한 패키지 목록 3. **진입점**: 노출된 CLI 명령어 4. **분류기**: PyPI용 메타데이터 == GitHub Secrets를 사용한 보안 === PyPI 토큰 설정 1. **PyPI에서 API 토큰 생성**: - PyPI에 로그인하세요 - 계정 설정 > API 토큰으로 이동하세요 - 적절한 권한으로 새 토큰을 생성하세요 1. **GitHub에 비밀을 추가**: - 리포지토리 설정 > 비밀 및 변수 > 작업 - 새로운 비밀을 이름을 지정하여 생성하세요`PYPI_API_TOKEN` - PyPI 토큰을 붙여넣으세요 [plantuml, secrets-flow, svg] ---- @startuml !theme plain actor Developer as dev participant "GitHub 저장소" as repo participant "GitHub 액션" as actions participant PyPI dev -> repo : Configure PYPI_API_TOKEN secret repo -> actions : Trigger CD pipeline on release actions -> actions : Access secret securely actions -> PyPI : Authenticate with token PyPI -> PyPI : Validate and publish package note over actions, PyPI Token never exposed in logs Automatic rotation possible end note @enduml ---- == 전체 배포 워크플로 === 배포 시퀀스 [plantuml, deployment-sequence, svg] ---- @startuml !theme plain actor Developer as dev participant "로컬 Git" as git participant "GitHub" as github participant "GitHub Actions" as actions participant PyPI participant "최종 사용자" as users dev -> git : git tag v1.0.0 dev -> git : git push origin v1.0.0 git -> github : Push tag dev -> github : Create release from tag github -> actions : Trigger CD pipeline actions -> actions : Checkout code actions -> actions : Setup Python environment actions -> actions : Install build tools actions -> actions : Build distributions (sdist + wheel) actions -> PyPI : Upload to PyPI with token PyPI -> PyPI : Validate and publish users -> PyPI : pip install playlist-downloader note over dev, github Release creation can be automated or done manually through GitHub UI end note @enduml ---- === 파이프라인 상태 [plantuml, pipeline-states, svg] ---- @startuml !theme plain [*] --> Idle Idle --> CI_Running : Push/PR created CI_Running --> CI_Success : All checks pass CI_Running --> CI_Failed : Linting/Tests fail CI_Success --> Idle : Merge completed CI_Failed --> Idle : Fix and retry Idle --> CD_Running : Release published CD_Running --> CD_Success : Package published CD_Running --> CD_Failed : Build/Upload error CD_Success --> Idle : Package available on PyPI CD_Failed --> Idle : Fix and retry release note on link #red : Blocks merge note on link #green : Allows deployment @enduml ---- == 모범 사례 및 최적화 === 1. 버전 관리 의미 있는 Git 태그를 사용하세요 : ---- git tag -a v1.2.3 -m "Release version 1.2.3" git push origin v1.2.3 === 2. 매트릭스 테스트 여러 Python 버전에서 테스트하기 : ```yaml ---- ---- strategy: matrix: python-version: [3.8, 3.9, "3.10", "3.11"] ---- === 3. 의존성 캐시 캐시로 빌드를 가속화하세요: ---- - name: Cache pip dependencies uses: actions/cache@v3 with: path: ~/.cache/pip key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }} === 4. 배포 환경 GitHub 환경을 사용하여 제어된 배포를 수행하세요 : ```yaml ---- ---- jobs: deploy: environment: production runs-on: ubuntu-latest ---- == 유스케이스 및 아키텍처 === 사용 사례 다이어그램 [plantuml, use-cases, svg] ---- @startuml !theme plain left to right direction actor "개발자" as dev actor "깃허브 액션" as ga actor "최종 사용자" as user package "CI/CD 시스템" { usecase "링팅 실행" as lint usecase "테스트 실행" as test usecase "빌드 패키지" as build usecase "PyPI에 게시" as publish usecase "릴리스 만들기" as release } dev --> lint : Pushes code dev --> test : Pushes code dev --> release : Creates release ga --> build : On release trigger ga --> publish : After successful build user --> publish : Downloads package lint .> test : triggers test .> build : on success build .> publish : on success @enduml ---- === 배포 아키텍처 [plantuml, deployment-architecture, svg] ---- @startuml !theme plain cloud "깃헙" { [Source Repository] [GitHub Actions] [Secrets Store] } cloud "PyPI" { [Package Registry] [Distribution Files] } node "CI/CD 파이프라인" { [Linting] [Testing] [Building] [Publishing] } [Source Repository] --> [GitHub Actions] : Triggers [GitHub Actions] --> [Linting] [Linting] --> [Testing] [Testing] --> [Building] [Building] --> [Publishing] [Publishing] --> [Package Registry] : Uploads [Secrets Store] --> [Publishing] : Provides token note as N1 Secure token-based authentication end note [Secrets Store] .. N1 @enduml ---- == 감시와 디버깅 === 로그 및 모니터링 GitHub Actions은 각 단계에 대한 자세한 로그를 제공합니다. 디버그하려면 : 1. **로그를 조사해 주세요**각각의 step 2. **디버그를 활성화하세요**와 함께`ACTIONS_STEP_DEBUG` 3. **아티팩트를 사용하세요**빌드 파일을 저장하기 위해 ---- - name: Upload build artifacts uses: actions/upload-artifact@v3 if: failure() with: name: build-logs path: build/ === 알림 슬랙 또는 이메일 알림을 추가하세요 : ```yaml ---- ---- - name: Notify on failure if: failure() uses: 8398a7/action-slack@v3 with: status: ${{ job.status }} webhook_url: ${{ secrets.SLACK_WEBHOOK }} ---- == 결론 GitHub Actions를 사용해 견고한 CI/CD 파이프라인을 구축하면 개발 경험이 근본적으로 바뀝니다. 린팅, 테스트, 배포를 자동화하면 : - **오류를 줄이세요**생산 중 - **주기를 가속화하세요**개발 - **신뢰를 개선하세요**당신의 릴리스에서 - **협업을 원활하게 하세요**팀으로 이 파이프라인은 linting 도구, 테스트 프레임워크, 또는 배포 대상을 조정하여 다양한 유형의 Python 프로젝트에 맞출 수 있습니다. 이러한 워크플로우의 초기 설정 투자는 배포 과정에서의 시간 절감과 수작업 오류 감소 덕분에 빠르게 회수됩니다. == 보충 자료 - https://docs.github.com/en/actions[GitHub Actions 문서] - https://packaging.python.org/[Python 패키징 가이드] - https://docs.pytest.org/[문서 Pytest] - https://docs.astral.sh/ruff/[Ruff 문서] - https://twine.readthedocs.io/[Twine 문서] ✅ 기능적인 파이프라인 도달! 이제 간단한 CI/CD 파이프라인이 있어 GitHub Actions에서 직접 테스트를 자동화하고 Python 패키지를 PyPI에 게시할 수 있습니다. 그러나 이 파이프라인은 의도적으로 최소한으로 유지됩니다. 아직 전문적인 맥락에서 필수적인 일부 측면을 다루지 않습니다 : 파이썬 멀티버전 테스트, 자동 보안 분석, Test PyPI를 통한 점진적 배포, 파이프라인 모니터링 및 메트릭, 버전 관리 자동화 및 현대적인 관례 통합 (pyproject.toml). 다음 섹션에서는 한 단계 더 나아갈 것입니다. 이 기본 파이프라인을 실제 산업용 배포 파이프라인, 즉 강력하고 안전한 형태로 변환하는 방법을 배우게 될 것입니다. 이렇게 변환된 파이프라인은 프로덕션 Python 프로젝트에 바로 사용할 준비가 될 것입니다. ----</code></pre> </div> </div> </div> </div> </div> </div> https://cheroliv.com/blog/2025/0084_disco_bot_discord_python_post.html Wed, 16 Jul 2025 00:00:00 +0000 blog/2025/0084_disco_bot_discord_python_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_소개">소개</a></li> <li><a href="#_현재_상황과_과제">현재 상황과 과제</a> <ul class="sectlevel2"> <li><a href="#_음악_api의_진화">음악 API의 진화</a></li> <li><a href="#_로그_중심_개발_접근법">로그 중심 개발 접근법</a></li> </ul> </li> <li><a href="#_개념_아키텍처">개념 아키텍처</a></li> <li><a href="#_스택_기술과_함수형_패러다임">스택 기술과 함수형 패러다임</a> <ul class="sectlevel2"> <li><a href="#_기술적_선택">기술적 선택</a></li> <li><a href="#_적용된_기능_원칙">적용된 기능 원칙</a></li> </ul> </li> <li><a href="#_애자일_방법론과_백로그">애자일 방법론과 백로그</a> <ul class="sectlevel2"> <li><a href="#_주요_에픽">주요 에픽</a> <ul class="sectlevel3"> <li><a href="#_에픽_1_인프라_봇_디스코드">에픽 1: 인프라 봇 디스코드</a></li> <li><a href="#_에픽_2_spotify_통합">에픽 2 : Spotify 통합</a></li> <li><a href="#_에픽_3_youtube_통합">에픽 3 : YouTube 통합</a></li> <li><a href="#_에픽_4_음악_기능">에픽 4 : 음악 기능</a></li> </ul> </li> <li><a href="#_상세한_사용자_스토리">상세한 사용자 스토리</a> <ul class="sectlevel3"> <li><a href="#_us1_1_봇_초기화">US1.1 : 봇 초기화</a></li> <li><a href="#_us2_1_스마트_spotify_검색">US2.1 : 스마트 Spotify 검색</a></li> <li><a href="#_us3_1_유튜브_복원력_있는_추출">US3.1 : 유튜브 복원력 있는 추출</a></li> </ul> </li> </ul> </li> <li><a href="#_로그_기반_개발_접근">로그 기반 개발 접근</a> <ul class="sectlevel2"> <li><a href="#_로깅_전략">로깅 전략</a></li> <li><a href="#_로그_구조">로그 구조</a></li> <li><a href="#_로그_디자인_예제">로그 디자인 예제</a></li> </ul> </li> <li><a href="#_pydantic을_사용한_검증_아키텍처">Pydantic을 사용한 검증 아키텍처</a> <ul class="sectlevel2"> <li><a href="#_데이터_모델">데이터 모델</a></li> </ul> </li> <li><a href="#_기능_오류_관리">기능 오류 관리</a> <ul class="sectlevel2"> <li><a href="#_모나드와_오류_처리">모나드와 오류 처리</a></li> </ul> </li> <li><a href="#_제한_회피_전략">제한 회피 전략</a> <ul class="sectlevel2"> <li><a href="#_멀티소스_접근">멀티소스 접근</a></li> </ul> </li> <li><a href="#_반복적_개발_계획">반복적 개발 계획</a> <ul class="sectlevel2"> <li><a href="#_스프린트_계획">스프린트 계획</a></li> <li><a href="#_품질_메트릭스">품질 메트릭스</a></li> </ul> </li> <li><a href="#_배포_및_모니터링">배포 및 모니터링</a> <ul class="sectlevel2"> <li><a href="#_생산_아키텍처">생산 아키텍처</a></li> <li><a href="#_주동적_모니터링">주동적 모니터링</a></li> </ul> </li> <li><a href="#_결론_및_전망">결론 및 전망</a> <ul class="sectlevel2"> <li><a href="#_다음_단계">다음 단계</a></li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_소개"><a class="anchor" href="#_소개"></a>소개</h2> <div class="sectionbody"> <div class="paragraph"> <p>Discord 봇을 개발하여 Spotify 및 YouTube API를 통합하는 것은 현대적인 기술적 도전 과제를 제시하며, 특히 최근의 제한 및 플랫폼의 변화에 직면해 있습니다. 이 글은 다음과 같은 방법론적 접근을 기반으로 합니다<strong>로그 기반 개발</strong>(LDD), 테스트 주도 개발의 확장이며, 파이썬을 사용한 함수형 프로그래밍 패러다임에 적용되었습니다.</p> </div> <div class="paragraph"> <p>우리 목표 : 현재 음악 API의 제약을 탐색하면서도 디스코드에서 원활한 사용자 경험을 제공할 수 있는 강력하고 유지보수 가능하며 확장 가능한 봇을 만드는 것이다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_현재_상황과_과제"><a class="anchor" href="#_현재_상황과_과제"></a>현재 상황과 과제</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_음악_api의_진화"><a class="anchor" href="#_음악_api의_진화"></a>음악 API의 진화</h3> <div class="paragraph"> <p>음악 플랫폼은 접근 정책을 크게 강화했습니다 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>스포티파이</strong>메타데이터에 대한 접근 제한, 할당량 제한</p> </li> <li> <p><strong>유튜브</strong>: 강화된 안티봇 정책, 인증 절차의 복잡화</p> </li> <li> <p><strong>디스코드</strong>: 새로운 보안 및 성능 요구 사항</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_로그_중심_개발_접근법"><a class="anchor" href="#_로그_중심_개발_접근법"></a>로그 중심 개발 접근법</h3> <div class="paragraph"> <p>LDD는 로그를 개발의 핵심에 배치함으로써 TDD를 확장한다 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>로그의 정의</strong>구현 전에</p> </li> <li> <p><strong>관찰을 통한 검증</strong>기대되는 행동</p> </li> <li> <p><strong>완전한 추적 가능성</strong>데이터 흐름</p> </li> <li> <p><strong>프로액티브 디버깅</strong>오류를 예상하여</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_개념_아키텍처"><a class="anchor" href="#_개념_아키텍처"></a>개념 아키텍처</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>@startuml !theme aws-orange package "디스코드 봇 코어" { [Command Handler] as CH [Event Listener] as EL [Log Manager] as LM } package "음악 통합 레이어" { [Spotify Client] as SC [YouTube Client] as YC [Audio Processor] as AP } package "기능적 핵심" { [Data Validation] as DV [Business Logic] as BL [Error Handling] as EH } package "외부 API" { [Spotify API] as SAPI [YouTube API] as YAPI [Discord API] as DAPI } CH --> BL EL --> BL BL --> DV BL --> EH BL --> LM SC --> SAPI YC --> YAPI CH --> DAPI DV ..> SC : validates DV ..> YC : validates AP --> SC AP --> YC LM --> EH : logs errors LM --> BL : logs operations @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_스택_기술과_함수형_패러다임"><a class="anchor" href="#_스택_기술과_함수형_패러다임"></a>스택 기술과 함수형 패러다임</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_기술적_선택"><a class="anchor" href="#_기술적_선택"></a>기술적 선택</h3> <div class="paragraph"> <p>우리 스택은 함수형 프로그래밍을 중심으로 구성됩니다 :</p> </div> <div class="dlist"> <dl> <dt class="hdlist1"><strong>PyMonade</strong></dt> <dd> <p>부작용 관리 및 함수 합성</p> </dd> <dt class="hdlist1"><strong>Pydantic</strong></dt> <dd> <p>타입 안전한 데이터 검증 및 직렬화</p> </dd> <dt class="hdlist1"><strong>비동기 입출력</strong></dt> <dd> <p>API를 위한 비동기 프로그래밍</p> </dd> <dt class="hdlist1"><strong>Structlog</strong></dt> <dd> <p>LDD용 구조화된 로깅</p> </dd> </dl> </div> </div> <div class="sect2"> <h3 id="_적용된_기능_원칙"><a class="anchor" href="#_적용된_기능_원칙"></a>적용된 기능 원칙</h3> <div class="listingblock"> <div class="content"> <pre>@startuml !theme plain title 기능적 데이터 흐름 participant "디스코드 명령" as DC participant "검증기" as V participant "비즈니스 로직" as BL participant "API 클라이언트" as AC participant "로거" as L DC -> V: Raw Input activate V V -> V: Pydantic Validation V -> L: Log Validation V --> DC: Maybe[ValidData] deactivate V DC -> BL: ValidData activate BL BL -> BL: Pure Computation BL -> L: Log Business Logic BL -> AC: API Request activate AC AC -> AC: IO Operation AC -> L: Log API Call AC --> BL: Maybe[Result] deactivate AC BL --> DC: Either[Error, Success] deactivate BL DC -> L: Log Final Result @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_애자일_방법론과_백로그"><a class="anchor" href="#_애자일_방법론과_백로그"></a>애자일 방법론과 백로그</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_주요_에픽"><a class="anchor" href="#_주요_에픽"></a>주요 에픽</h3> <div class="paragraph"> <p>우리 개발은 4개의 주요 에픽을 중심으로 구성됩니다:</p> </div> <div class="sect3"> <h4 id="_에픽_1_인프라_봇_디스코드"><a class="anchor" href="#_에픽_1_인프라_봇_디스코드"></a>에픽 1: 인프라 봇 디스코드</h4> <div class="paragraph"> <p><strong>Valeur métier</strong> : 탄탄하고 확장 가능한 기반</p> </div> <div class="paragraph"> <p><strong>수용 기준</strong> : - 안정적인 Discord 연결과 재접속 관리 - 모듈형 명령 시스템 통합된 구조화된 로깅 - 중앙 집중 오류 관리</p> </div> </div> <div class="sect3"> <h4 id="_에픽_2_spotify_통합"><a class="anchor" href="#_에픽_2_spotify_통합"></a>에픽 2 : Spotify 통합</h4> <div class="paragraph"> <p><strong>비즈니스 가치</strong> : 음악 메타데이터 접근</p> </div> <div class="paragraph"> <p><strong>수용 기준</strong> : - 안전한 OAuth2 인증 - 스마트 캐시를 사용한 트랙 검색 - API 할당량 관리 - 네트워크 오류 시 대체</p> </div> </div> <div class="sect3"> <h4 id="_에픽_3_youtube_통합"><a class="anchor" href="#_에픽_3_youtube_통합"></a>에픽 3 : YouTube 통합</h4> <div class="paragraph"> <p><strong>업무 가치</strong> : 오디오 콘텐츠에 대한 액세스</p> </div> <div class="paragraph"> <p><strong>수용 기준</strong> : - 제한 사항의 합법적인 회피 - 최적화된 오디오 추출 - 비공개/삭제된 비디오 관리 - 유튜브의 ToS 준수</p> </div> </div> <div class="sect3"> <h4 id="_에픽_4_음악_기능"><a class="anchor" href="#_에픽_4_음악_기능"></a>에픽 4 : 음악 기능</h4> <div class="paragraph"> <p><strong>업무 가치</strong> : 완전한 사용자 경험</p> </div> <div class="paragraph"> <p><strong>수락 기준</strong> : - 고품질 오디오 강의 - 스마트 재생 큐 - Discord 음성 명령어 - 크로스 플랫폼 동기화</p> </div> </div> </div> <div class="sect2"> <h3 id="_상세한_사용자_스토리"><a class="anchor" href="#_상세한_사용자_스토리"></a>상세한 사용자 스토리</h3> <div class="sect3"> <h4 id="_us1_1_봇_초기화"><a class="anchor" href="#_us1_1_봇_초기화"></a>US1.1 : 봇 초기화</h4> <div class="paragraph"> <p><strong>En tant que</strong> 개발자 <strong>나는 원해</strong> 신뢰성 있게 연결되는 디스코드 봇 <strong>를 위해</strong> 서비스의 가용성을 보장</p> </div> <div class="paragraph"> <p><strong>DoD (완료의 정의)</strong> : - [ ] 봇이 시작 시 자동으로 연결됩니다 - [ ] 구조화된 로그는 각 단계를 문서화합니다. - [ ] 연결이 끊어질 경우 자동 재연결 - [ ] 통합 테스트 통과</p> </div> </div> <div class="sect3"> <h4 id="_us2_1_스마트_spotify_검색"><a class="anchor" href="#_us2_1_스마트_spotify_검색"></a>US2.1 : 스마트 Spotify 검색</h4> <div class="paragraph"> <p>Discord 사용자로서 저는 Spotify에서 곡을 검색하고 싶어요 <strong>목적으로</strong> 음악을 발견하고 공유하기</p> </div> <div class="paragraph"> <p><strong>DoD</strong> : - [ ] 명령`/search`기능적인 - [ ] 관련 결과와 메타데이터 - [ ] 로컬 캐시로 쿼리 최적화 - [ ] 우아한 API 오류 처리</p> </div> </div> <div class="sect3"> <h4 id="_us3_1_유튜브_복원력_있는_추출"><a class="anchor" href="#_us3_1_유튜브_복원력_있는_추출"></a>US3.1 : 유튜브 복원력 있는 추출</h4> <div class="paragraph"> <p>시스템으로서 <strong>나는</strong> 유튜브 오디오를 신뢰할 수 있게 추출하고 싶다 <strong>Afin de</strong> 서비스의 연속성을 유지하기 위해</p> </div> <div class="paragraph"> <p><strong>DoD</strong> : - [ ] ToS 위반 없이 추출 - [ ] 최적의 오디오 품질 - [ ] 지리적 제한 관리 - [ ] 상세한 작업 로그</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_로그_기반_개발_접근"><a class="anchor" href="#_로그_기반_개발_접근"></a>로그 기반 개발 접근</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_로깅_전략"><a class="anchor" href="#_로깅_전략"></a>로깅 전략</h3> <div class="listingblock"> <div class="content"> <pre>@startuml !theme spacelab title 로그 기반 개발 흐름 start :Define Expected Behavior; note right: Spécification des logs attendus :Write Log Assertions; note right: Tests basés sur les logs :Implement Minimal Code; note right: Code juste suffisant :Run & Observe Logs; note right: Validation comportementale if (Logs Match Expectations?) then (yes) :Refactor & Optimize; note right: Amélioration continue else (no) :Debug via Logs; note right: Analyse des écarts :Fix Implementation; endif :Integration Tests; note right: Validation end-to-end stop @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_로그_구조"><a class="anchor" href="#_로그_구조"></a>로그 구조</h3> <div class="paragraph"> <p>우리의 LDD 접근 방식은 의미 수준을 갖는 구조화된 로그를 사용합니다:</p> </div> <div class="dlist"> <dl> <dt class="hdlist1"><strong>흔적</strong></dt> <dd> <p>상세한 데이터 흐름</p> </dd> <dt class="hdlist1"><strong>디버그</strong></dt> <dd> <p>함수의 내부 상태</p> </dd> <dt class="hdlist1"><strong>정보</strong></dt> <dd> <p>성공적인 비즈니스 운영</p> </dd> <dt class="hdlist1"><strong>경고</strong></dt> <dd> <p>열화된 상황이지만 관리되는</p> </dd> <dt class="hdlist1"><strong>오류</strong></dt> <dd> <p>개입이 필요한 오류</p> </dd> <dt class="hdlist1"><strong>CRITICAL</strong></dt> <dd> <p>시스템 장애</p> </dd> </dl> </div> </div> <div class="sect2"> <h3 id="_로그_디자인_예제"><a class="anchor" href="#_로그_디자인_예제"></a>로그 디자인 예제</h3> <div class="paragraph"> <p>Spotify 검색 기능을 구현하기 전에 그 로그를 정의합니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">INFO: spotify.search.start query="bohemian rhapsody" user_id=123456 DEBUG: spotify.search.validation query_length=16 safe_chars=true DEBUG: spotify.search.api_call endpoint="/search" params={...} INFO: spotify.search.success results_count=15 duration_ms=340</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_pydantic을_사용한_검증_아키텍처"><a class="anchor" href="#_pydantic을_사용한_검증_아키텍처"></a>Pydantic을 사용한 검증 아키텍처</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_데이터_모델"><a class="anchor" href="#_데이터_모델"></a>데이터 모델</h3> <div class="paragraph"> <p>우리의 기능적 접근 방식은 사전 검증을 우선시합니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml !theme cerulean-outline class SpotifyTrack { +id: str +name: str +artists: List[str] +duration_ms: int +external_urls: Dict[str, str] -- +validate_duration() : bool +to_discord_embed() : Embed } class YouTubeVideo { +id: str +title: str +duration: timedelta +available: bool -- +validate_availability() : bool +extract_audio_url() : Optional[str] } class DiscordCommand { +command: str +args: List[str] +user: User +channel: Channel -- +validate_permissions() : bool +log_execution() : None } SpotifyTrack --|> BaseModel YouTubeVideo --|> BaseModel DiscordCommand --|> BaseModel @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_기능_오류_관리"><a class="anchor" href="#_기능_오류_관리"></a>기능 오류 관리</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_모나드와_오류_처리"><a class="anchor" href="#_모나드와_오류_처리"></a>모나드와 오류 처리</h3> <div class="paragraph"> <p>PyMonade를 사용하면 오류를 우아하게 관리할 수 있습니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml !theme toy title 오류 처리 흐름 participant "명령" as C participant "아마도 모나드" as M participant "Either 모나드" as E participant "로거" as L C -> M: search_query activate M alt Valid Query M -> E: Success(query) activate E E -> E: api_call() alt API Success E -> L: log_success() E --> C: Right(result) else API Error E -> L: log_api_error() E --> C: Left(api_error) end deactivate E else Invalid Query M -> L: log_validation_error() M --> C: Nothing end deactivate M @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_제한_회피_전략"><a class="anchor" href="#_제한_회피_전략"></a>제한 회피 전략</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_멀티소스_접근"><a class="anchor" href="#_멀티소스_접근"></a>멀티소스 접근</h3> <div class="paragraph"> <p>API 제한에 직면하여 우리는 다각화 전략을 채택하고 있습니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml !theme mars title 멀티 소스 전략 start :User Request; :Primary Source\n(Spotify); if (Available?) then (yes) :Return Spotify Data; stop else (no) :Log Fallback; :Secondary Source\n(YouTube Music); if (Available?) then (yes) :Return YouTube Data; stop else (no) :Tertiary Source\n(Local Cache); if (Available?) then (yes) :Return Cached Data; :Log Cache Hit; stop else (no) :Return Error; :Log Complete Failure; stop end end end @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_반복적_개발_계획"><a class="anchor" href="#_반복적_개발_계획"></a>반복적 개발 계획</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_스프린트_계획"><a class="anchor" href="#_스프린트_계획"></a>스프린트 계획</h3> <div class="paragraph"> <p>우리의 개발은 2주 스프린트 사이클을 따릅니다:</p> </div> <div class="dlist"> <dl> <dt class="hdlist1"><strong>스프린트 1-2</strong></dt> <dd> <p>인프라스트럭처와 디스코드 봇 코어</p> </dd> <dt class="hdlist1"><strong>스프린트 3-4</strong></dt> <dd> <p>Spotify와 LDD 통합</p> </dd> <dt class="hdlist1"><strong>스프린트 5-6</strong></dt> <dd> <p>YouTube 통합 및 우회</p> </dd> <dt class="hdlist1"><strong>스프린트 7-8</strong></dt> <dd> <p>고급 음악 기능</p> </dd> <dt class="hdlist1"><strong>스프린트 9-10</strong></dt> <dd> <p>최적화 및 생산</p> </dd> </dl> </div> </div> <div class="sect2"> <h3 id="_품질_메트릭스"><a class="anchor" href="#_품질_메트릭스"></a>품질 메트릭스</h3> <div class="paragraph"> <p>각 스프린트는 다음과 같이 평가됩니다:</p> </div> <div class="ulist"> <ul> <li> <p><strong>로그 커버리지</strong>중요한 경로의 90% 초과</p> </li> <li> <p><strong>API 신뢰성</strong>: <1% 처리되지 않은 오류</p> </li> <li> <p><strong>성능</strong>: <500ms 평균 응답 시간</p> </li> <li> <p><strong>유지성</strong>: 순환 복잡도 <10</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_배포_및_모니터링"><a class="anchor" href="#_배포_및_모니터링"></a>배포 및 모니터링</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_생산_아키텍처"><a class="anchor" href="#_생산_아키텍처"></a>생산 아키텍처</h3> <div class="listingblock"> <div class="content"> <pre>@startuml !theme vibrant cloud "디스코드 서버" { [User Commands] } node "프로덕션 환경" { [Discord Bot] [Log Aggregator] [Metrics Collector] [Health Monitor] } database "로그 저장소" { [Structured Logs] [Error Traces] [Performance Metrics] } cloud "외부 API" { [Spotify API] [YouTube API] } [User Commands] --> [Discord Bot] [Discord Bot] --> [Log Aggregator] [Discord Bot] --> [Spotify API] [Discord Bot] --> [YouTube API] [Log Aggregator] --> [Structured Logs] [Metrics Collector] --> [Performance Metrics] [Health Monitor] --> [Error Traces] @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_주동적_모니터링"><a class="anchor" href="#_주동적_모니터링"></a>주동적 모니터링</h3> <div class="paragraph"> <p>LDD는 스마트 모니터링을 용이하게 합니다 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>로그 패턴 기반 경고</strong></p> </li> <li> <p><strong>행동 이상 탐지</strong></p> </li> <li> <p><strong>실시간 비즈니스 메트릭스</strong></p> </li> <li> <p><strong>로그 상관을 통한 디버깅 지원</strong></p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_결론_및_전망"><a class="anchor" href="#_결론_및_전망"></a>결론 및 전망</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 방법론적 접근은 함수형 프로그래밍 패러다임의 이점과 Log Driven Development의 견고함을 결합합니다. 이를 통해 우리는 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>문제를 예측하다</strong>미리 설계된 로그 덕분에</p> </li> <li> <p><strong>품질을 유지하다</strong>지속적인 검증을 통해</p> </li> <li> <p><strong>빠르게 적응해</strong>APIs의 변경 사항에</p> </li> <li> <p><strong>추적 가능성 보장</strong>작업의 완료</p> </li> </ol> </div> <div class="paragraph"> <p>반복적 개발과 모듈러 아키텍처는 변화하는 음악 플랫폼의 제약에 대한 확장성을 보장한다.</p> </div> <div class="sect2"> <h3 id="_다음_단계"><a class="anchor" href="#_다음_단계"></a>다음 단계</h3> <div class="ulist"> <ul> <li> <p><strong>1단계</strong>: PyMonade를 사용한 코어 구현</p> </li> <li> <p><strong>2단계</strong>: 스마트 캐시가 적용된 Spotify 통합</p> </li> <li> <p><strong>3단계</strong>: 탄력적인 YouTube 솔루션</p> </li> <li> <p><strong>4단계</strong>: 고급 기능 및 최적화</p> </li> </ul> </div> <div class="paragraph"> <p>이 탄탄한 개념적 기반은 기술적 과제를 헤쳐 나가면서도 뛰어난 사용자 경험을 제공할 수 있게 해줄 것입니다.</p> </div> <hr> <div class="paragraph"> <p><strong>이 문서는 각 구성 요소의 구현을 상세히 설명하는 기술 시리즈로 이어지며, 코드 예시와 기능적 패턴을 포함합니다.</strong></p> </div> </div> </div> </div> https://cheroliv.com/blog/2025/0083_cold_computer_post.html Tue, 15 Jul 2025 00:00:00 +0000 blog/2025/0083_cold_computer_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_이_가이드의_목적">이 가이드의 목적</a></li> <li><a href="#_전제_조건">전제 조건</a></li> <li><a href="#_도구를_설치하고_구성하세요">도구를 설치하고 구성하세요</a> <ul class="sectlevel2"> <li><a href="#_lm_sensors_센서를_감지하기_위해">lm-sensors` 센서를 감지하기 위해</a></li> <li><a href="#_tlp_지능형_에너지_관리자">tlp` : 지능형 에너지 관리자</a></li> <li><a href="#_cpufrequtils_cpu_주파수_제한">cpufrequtils` : CPU 주파수 제한</a></li> <li><a href="#_auto_cpufreq_간소화된_동적_관리">auto-cpufreq` : 간소화된 동적 관리</a></li> <li><a href="#_thermald_자동_열_보호">thermald` : 자동 열 보호</a></li> </ul> </li> <li><a href="#_실시간_모니터링">실시간 모니터링</a> <ul class="sectlevel2"> <li><a href="#_sensors_명령줄에서">sensors` 명령줄에서</a></li> <li><a href="#_gui_옵션_psensor">GUI 옵션 : `psensor</a></li> </ul> </li> <li><a href="#_추가_팁">추가 팁</a></li> <li><a href="#_시스템을_청소하여_과부하를_제한">시스템을 청소하여 과부하를 제한</a></li> <li><a href="#_더_깊이_가기">더 깊이 가기</a></li> <li><a href="#_결론">결론</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>Ubuntu에서 노트북이 비정상적으로 과열되고 있다고 느끼십니까? 이 글은 당신에게 한 가지 접근 방식을 제안합니다.<strong>소프트웨어</strong>완전한 를 위한<strong>냉각하다</strong>, <strong>감시하다</strong> et <strong>온도 제어</strong>당신의 기계의</p> </div> </div> </div> <div class="sect1"> <h2 id="_이_가이드의_목적">이 가이드의 목적</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>컴퓨터의 전체 온도를 낮추기</p> </li> <li> <p>에너지 관리 최적화</p> </li> <li> <p>중요한 구성 요소 모니터링 (CPU, GPU, etc.)</p> </li> <li> <p>로 인한 지연을 피하기<strong>열 스로틀링</strong></p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre>@startuml start :Installer les outils; :Analyser les capteurs; :Appliquer des réglages; note right: cpufreq, tlp, auto-cpufreq :Surveiller en temps réel; stop @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_전제_조건">전제 조건</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Ubuntu 머신 (20.04 이상 권장)</p> </li> <li> <p>인터넷 연결</p> </li> <li> <p>명령줄 역량 (초보자~중급자)</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_도구를_설치하고_구성하세요">도구를 설치하고 구성하세요</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_lm_sensors_센서를_감지하기_위해">lm-sensors` 센서를 감지하기 위해</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install lm-sensors sudo sensors-detect sensors</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>답변해`YES`모든 질문의`sensors-detect`모듈을 감지하기 위해.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_tlp_지능형_에너지_관리자">tlp` : 지능형 에너지 관리자</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install tlp tlp-rdw sudo systemctl enable tlp sudo systemctl start tlp</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre>@startuml (*) --> "TLP이 활성화되었나요?" if "예" then --> [yes] "소비 감소" --> "CPU 주파수 제한" else --> [no] "TLP 시작" --> "자동 활성화" endif -->(*) @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_cpufrequtils_cpu_주파수_제한">cpufrequtils` : CPU 주파수 제한</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install cpufrequtils cpufreq-info sudo cpufreq-set -g powersave</code></pre> </div> </div> <div class="ulist"> <ul> <li> <p><code>powersave</code>: 주파수 피크를 제한</p> </li> <li> <p><code>performance</code>: 온도보다 전력을 우선시한다</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_auto_cpufreq_간소화된_동적_관리">auto-cpufreq` : 간소화된 동적 관리</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">git clone https://github.com/AdnanHodzic/auto-cpufreq.git cd auto-cpufreq sudo ./auto-cpufreq-installer sudo auto-cpufreq --install</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre>@startuml start :Analyse charge système; :Réglage fréquence CPU; :Vérification température; :Adaptation dynamique; stop @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_thermald_자동_열_보호">thermald` : 자동 열 보호</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install thermald sudo systemctl enable thermald sudo systemctl start thermald</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_실시간_모니터링">실시간 모니터링</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_sensors_명령줄에서">sensors` 명령줄에서</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">watch -n 2 sensors</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_gui_옵션_psensor">GUI 옵션 : `psensor</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install psensor</code></pre> </div> </div> <div class="paragraph"> <p>CPU, GPU, 팬을 위한 간단한 그래픽 인터페이스.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_추가_팁">추가 팁</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>탭과 무거운 응용 프로그램 닫기 (예: 브라우저)</p> </li> <li> <p>배터리에서 과도한 사용을 피하십시오</p> </li> <li> <p>통해 프로세스를 모니터링`htop`:</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install htop htop</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_시스템을_청소하여_과부하를_제한">시스템을 청소하여 과부하를 제한</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt autoremove sudo apt autoclean sudo journalctl --vacuum-time=3d</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_더_깊이_가기">더 깊이 가기</h2> <div class="sectionbody"> <div class="paragraph"> <p>당신은 서비스를 생성할 수 있습니다.`systemd`시작 시 자동으로 일부 설정을 적용하도록 맞춤 설정된 다음 글에 예시를 원하시나요? 알려 주세요!</p> </div> </div> </div> <div class="sect1"> <h2 id="_결론">결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>이러한 간단한 도구들을 조합함으로써, 당신은 얻게 될 것입니다 :</p> </div> <div class="ulist"> <ul> <li> <p>제어된 CPU 온도</p> </li> <li> <p>환기 소음 감소</p> </li> <li> <p>더 나은 자율성</p> </li> </ul> </div> <div class="paragraph"> <p>정기적으로 온도를 모니터링하여 과열을 방지하는 것을 잊지 마세요.</p> </div> <div class="paragraph"> <p><em><em>_ CPU를 녹이는 것보다 예방하는 것이 더 낫다. </em>_</em></p> </div> </div> </div> https://cheroliv.com/blog/2025/0082_ui_struggle_post.html Mon, 14 Jul 2025 00:00:00 +0000 blog/2025/0082_ui_struggle_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_전장_모형_세_개의_브라우저_여러_렌더링">전장: 모형, 세 개의 브라우저, 여러 렌더링</a></li> <li><a href="#_문제_1_hero_섹션의_날아가는_카드">문제 1: 'Hero' 섹션의 날아가는 카드</a></li> <li><a href="#_문제_2_식인_네비게이션_바">문제 2: 식인 네비게이션 바</a></li> <li><a href="#_문제_3_무질서한_타이포그래피">문제 3: 무질서한 타이포그래피</a></li> <li><a href="#_문제_4_넘치는_내비게이션_바">문제 4: 넘치는 내비게이션 바</a></li> <li><a href="#_문제_5_보이지_않는_햄버거_메뉴">문제 5 : 보이지 않는 햄버거 메뉴</a></li> <li><a href="#_결론_끈질긴_디버깅의_교훈">결론 : 끈질긴 디버깅의 교훈</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>읽는 데 걸리는 시간:</strong> 약 7분 <strong>레벨 :</strong> 중급</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>이 상세한 사례 연구에서 우리는 Bootstrap 5.2를 사용해 UI 프로토타입을 만들 때 발생하는 가장 일반적인 브라우저 호환성 문제와 때때로 가장 성가신 문제들을 분석할 것입니다. Flexbox 관리부터 글꼴 렌더링의 미묘함까지, Firefox에서 어긋난 디자인을 모든 브라우저에서 픽셀 완벽한 경험으로 변환하는 디버깅 과정을 알아보세요.</p> </div> <hr> </div> </div> <div class="sect1"> <h2 id="_전장_모형_세_개의_브라우저_여러_렌더링">전장: 모형, 세 개의 브라우저, 여러 렌더링</h2> <div class="sectionbody"> <div class="paragraph"> <p>모든 프론트엔드 개발자는 이 감정을 잘 알죠. 몇 시간의 작업 끝에 드디어 디자인이 완벽해집니다. 정렬은 깔끔하고, 타이포그래피는 우아하며, 애니메이션은 부드러워요. 만족감에 한숨이 나오고, Chrome(또는 Brave, 혹은 Edge)에서 작업을 감상한 뒤, 혹시 모를 상황을 대비해 Firefox에서 프로젝트를 열어봅니다. 그리고 그곳에서 재앙이 일어납니다. 요소들이 넘쳐흐르고, 정렬이 깨지고, 글꼴 크기가 제멋대로라… 아름다운 조화가 사라져 버렸습니다.</p> </div> <div class="paragraph"> <p>이것은 정확히 우리가 새로운 포트폴리오 인터페이스를 개발하면서 직면한 시나리오입니다. 사양은 간단했습니다: 현대적이고 반응형인 홈페이지, 테마 선택기(라이트, 다크, 높은 대비)를 갖추고, <strong>vanilla JavaScript*와 *Bootstrap 5.2</strong> 최신 버전을 사용하는 것입니다.</p> </div> <div class="paragraph"> <p>이 기사는 기적 같은 솔루션 목록이 아닙니다. 이는 우리 디버깅 세션의 로그이며, Blink(Chromium, Brave) 엔진과 Gecko(Firefox) 엔진 간의 렌더링 차이의 '왜’에 대한 심층 분석입니다. 그리고 강력하고 현대적인 솔루션이 언제나 임시 방편보다 더 낫다는 것을 보여줍니다.</p> </div> <div class="listingblock"> <div class="title">사용 사례 다이어그램 : 디버깅 과정</div> <div class="content"> <pre>@startuml left to right direction actor "프론트엔드 개발자" as Dev rectangle "Bootstrap 5 UI 목업" { usecase "Flexbox 정렬 수정" as UC1 usecase "패딩을 동적으로 조정 (JS)" as UC2 usecase "타이포그래피 제어 (clamp())" as UC3 usecase "메뉴 오버플로 해결" as UC4 usecase "메뉴 아이콘을 보이게 하다" as UC5 } actor "파이어폭스 브라우저" as Firefox Dev -- (UC1) Dev -- (UC2) Dev -- (UC3) Dev -- (UC4) Dev -- (UC5) (UC1) ..> Firefox : <<extend>> (UC2) ..> Firefox : <<extend>> (UC3) ..> Firefox : <<extend>> (UC4) ..> Firefox : <<extend>> (UC5) ..> Firefox : <<extend>> note right of Firefox : Révèle les problèmes de compatibilité @enduml</pre> </div> </div> <div class="listingblock"> <div class="title">컴포넌트 다이어그램: 프론트엔드 솔루션 아키텍처</div> <div class="content"> <pre>@startuml !theme plain package "솔루션 프론트엔드" { component "HTML (템플릿 FTL)" as HTML component "script.js" as JS component "styles.css" as CSS interface "DOM 조작" as iDOM interface "CSS 수정" as iCSS } package "프레임워크" { component "Bootstrap 5.2" as BS interface "CSS 변수" as iVars interface "유틸리티 클래스" as iUtils } HTML ..> iDOM : nécessite JS ..> iDOM : réalise HTML ..> iCSS : nécessite CSS ..> iCSS : réalise CSS ..> iVars : nécessite BS ..> iVars : fournit HTML ..> iUtils : utilise BS ..> iUtils : fournit note right of JS - Mesure la hauteur de la navbar - Applique le padding dynamiquement end note note right of CSS - Utilise clamp() pour la typographie - Réduit les marges du menu - Surcharge l'icône du menu via les variables end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_문제_1_hero_섹션의_날아가는_카드">문제 1: 'Hero' 섹션의 날아가는 카드</h2> <div class="sectionbody"> <div class="paragraph"> <p>첫 번째 버그는 가장 눈에 띄는 버그였습니다. 환영 섹션("hero")은 두 개의 열로 구성되어 있습니다: 왼쪽에는 메인 타이틀이 있고, 오른쪽에는 소개 카드가 있습니다.</p> </div> <div class="ulist"> <ul> <li> <p><strong>증상:</strong>Chrome와 Brave에서는 두 열이 수직으로 완벽히 중앙에 위치했습니다. Firefox에서는 오른쪽 카드가 설명도 없이 왼쪽 텍스트 아래에 떨어졌습니다.</p> </li> <li> <p><strong>조사 :</strong>하지만 HTML 코드는 간단하고 올바른 것처럼 보였으며, Bootstrap의 표준 클래스를 사용하고 있었습니다.</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><section id="home" class="hero-section"> <div class="container"> <!-- Cette ligne est la clé du problème --> <div class="row align-items-center min-vh-100"> <div class="col-lg-6"> <!-- Contenu de gauche --> </div> <div class="col-lg-6"> <!-- Carte de droite --> </div> </div> </div> </section></code></pre> </div> </div> <div class="paragraph"> <p>우리 맞춤 CSS용`.hero-section`정의하고 있었다`display: flex` et <code>align-items: center</code>, 그리고 수업`min-vh-100`줄에 최소 높이를 주었다 (<code>div.row</code>). 그럼 왜 Firefox는 열을 가운데 맞히지 않았나요?</p> </div> <div class="ulist"> <ul> <li> <p><strong>근본적인 원인 :</strong>이것은 렌더링 엔진이 암시적 높이를 해석하는 방식에 대한 모범 사례입니다. 라`<section>`가지고 있었다`min-height`, 그러나`height`명시적. 적용하기 위해`align-items-center`내부에`div.row`, Firefox는 이 컨테이너의 기준 높이를 알아야 합니다. 부모 요소와 (<code>div.container</code> et la `<section>`그녀 자신은 높이가 없었다<strong>엄격한</strong>, Firefox가 길을 잃었습니다. Blink 엔진은 더 permissive하여 의도를 '추측’하고 요소를 가운데로 맞춥니다. Gecko는 사양에 더 충실하여 그렇게 하지 않습니다.</p> </li> <li> <p><strong>해결책:</strong>높이를 명시적으로 만듭니다. 우리는 그것을 강제했습니다.<code>.container</code> et le `.row`해당 부모의 높이 100%를 차지하기 위해 유틸리티 클래스를 사용`h-100`Bootstrap의.</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><section id="home" class="hero-section"> <div class="container h-100"> <div class="row align-items-center min-vh-100 h-100"> <!-- ... --> </div> </div> </section></code></pre> </div> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p>누가`align-items`Flexbox가 수직 축에서 예상대로 작동하지 않으면 컨테이너에 높이가 있는지 항상 확인하세요 (<code>height</code> ou <code>min-height</code>) 정의되고, 문제가 계속되면 (특히 Firefox에서), 중간 부모 컨테이너가 이 높이를 적절히 전달하도록 확인하세요.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_문제_2_식인_네비게이션_바">문제 2: 식인 네비게이션 바</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">영웅 섹션이 정렬된 후, 다른 문제가 발생했습니다: 내비게이션 바, 그 클래스와 함께`fixed-top`, 제목 위에 겹쳐 있었다. 하나`padding-top: 80px`섹션 "Hero"에 해결책으로 적용되었습니다.</div> <ul> <li> <p><strong>증상 :</strong> Le `padding`Chrome에서는 충분했지만, Firefox에서는 아니었다. Firefox에서는 제목이 항상 부분적으로 가려져 있었다.</p> </li> <li> <p><strong>근본적인 원인:</strong>매직 넘버" 사용`80px`)는 매우 나쁜 관행입니다. 네비게이션 바와 같은 요소의 높이는 폰트 렌더링, 간격, 심지어 사용자 옵션의 미세한 차이로 인해 브라우저마다 몇 픽셀씩 달라질 수 있습니다. 고정된 값에 의존하는 것은 취약한 디자인을 만드는 방법입니다.</p> </li> <li> <p><strong>해결책 :</strong>자바스크립트로 구현된 동적이고 완벽한 솔루션입니다. 우리는 작은 스크립트를 작성했습니다 :</p> </li> <li> <p>페이지 렌더링 후 네비게이션 바의 <strong>실제</strong> 높이를 측정합니다.</p> </li> <li> <p>이 측정 높이를 적용해`padding-top`Hero 섹션으로</p> </li> <li> <p>창 크기가 조정될 때마다 이 함수를 다시 실행하여 변경 사항에 적응(예: 햄버거 메뉴로 전환).</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">document.addEventListener('DOMContentLoaded', function() { function adjustHeroPadding() { const navbar = document.querySelector('.navbar.fixed-top'); const heroSection = document.querySelector('.hero-section'); if (navbar && heroSection) { const navbarHeight = navbar.offsetHeight; heroSection.style.paddingTop = navbarHeight + 'px'; } } // Ajuster au chargement et au redimensionnement adjustHeroPadding(); window.addEventListener('resize', adjustHeroPadding); });</code></pre> </div> </div> <div class="listingblock"> <div class="title">시퀀스 다이어그램 : 패딩의 동적 조정</div> <div class="content"> <pre>@startuml title 칸니발 네비게이션 바 문제 해결 actor Utilisateur participant "브라우저" as Browser participant "script.js" as JS participant "DOM" as DOM Utilisateur -> Browser: Charge la page activate Browser Browser -> JS: Déclenche l'événement 'DOMContentLoaded' activate JS JS -> DOM: querySelector('.navbar.fixed-top') activate DOM DOM --> JS: Retourne l'élément Navbar deactivate DOM JS -> DOM: querySelector('.hero-section') activate DOM DOM --> JS: Retourne l'élément Hero deactivate DOM JS -> DOM: navbar.offsetHeight activate DOM DOM --> JS: Retourne la hauteur calculée (ex: 83px) deactivate DOM JS -> DOM: heroSection.style.paddingTop = "83px" activate DOM deactivate DOM deactivate JS deactivate Browser ... Plus tard ... Utilisateur -> Browser: Redimensionne la fenêtre activate Browser Browser -> JS: Déclenche l'événement 'resize' activate JS JS -> JS: Exécute à nouveau adjustHeroPadding() note right of JS: Le processus de mesure et\nd'application du padding se répète. deactivate JS deactivate Browser @enduml</pre> </div> </div> <div class="paragraph"> <p>동시에 우리는 물론 규칙을 삭제했습니다.<code>padding-top: 80px;`우리 파일의`styles.css</code>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_문제_3_무질서한_타이포그래피">문제 3: 무질서한 타이포그래피</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">다음 우려는 브랜드 이미지에 가장 해로운 것이었으니, 바로 메인 제목의 크기였다.</div> <ul> <li> <p><strong>증상 :</strong>파이어폭스에서는 제목 '개발자 강사…​'의 글꼴이 엄청나게 커서 거의 충격적이었으나, 다른 브라우저에서는 조화로웠습니다.</p> </li> <li> <p><strong>근본 원인 :</strong>제목은 한 클래스를 사용했다.`display-4`Bootstrap의. 이러한 클래스는 반응형 글꼴 크기를 사용하며, 종종 단위를 기준으로 합니다.`rem`그리고 미디어 쿼리. 한 번 더, Firefox의 렌더링 알고리즘이 "Inter" 글꼴과 결합되면서 1920x1080 해상도에서 훨씬 더 큰 크기로 계산되었습니다.</p> </li> <li> <p><strong>해결책:</strong>CSS 함수를 사용해 제어하기`clamp()<code>. 이 기능은 유동적인 타이포그래피에 혁명을 일으킵니다. 이는 세 가지 값으로 글꼴 크기를 정의할 수 있게 해줍니다: 최소 크기, '선호' 크기(뷰의 너비에 맞춰 조정됨),`vw</code>), 그리고 최대 크기.</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">.hero-content h1 { color: var(--text-primary); line-height: 1.2; /* Min: 2rem Préférée: s'adapte à la vue Max: 2.5rem (40px) */ font-size: clamp(2rem, 1.2rem + 1.5vw, 2.5rem); }</code></pre> </div> </div> <div class="paragraph"> <p>와`clamp()<code>, 우리는 브라우저에게 말할 수 있었습니다 : "화면에 맞춰 글씨 크기를 키워, 초과하지 마<strong>결코</strong>의 제한`2.5rem</code>. 이는 모든 브라우저에서 렌더링을 즉시 조화시켰으며, 이를 통해 최종적인 미학에 대한 절대적인 통제를 제공했습니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_문제_4_넘치는_내비게이션_바">문제 4: 넘치는 내비게이션 바</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">이 문제는 우리에게 가장 많은 어려움을 주었고, 결국 렌더링의 미세한 차이의 본질을 드러냈다.</div> <ul> <li> <p><strong>증상:</strong>1920x1080 해상도의 화면에서 메뉴의 마지막 링크('Blog', 'Contact')가 화면 오른쪽 밖으로 밀려 났지만, 이것은 Firefox에서만 발생했습니다.</p> </li> <li> <p><strong>근본적인 원인:</strong>몇 번의 시도 실패 후 (Bootstrap의 브레이크포인트를 변경하는)<code>lg</code> à <code>xl`그리고`xxl</code>), 우리는 이해했습니다. 문제는 Bootstrap의 로직이 아니라 단지 너비 계산이었습니다. 파이어폭스에서는 모든 링크의 너비 합계, 이들의`padding` et `margin`서브 픽셀 수준에서, 그것은 1920 픽셀보다 <strong>약간</strong> 더 컸습니다. Chrome에서는 이 합이 <strong>약간</strong> 더 작았습니다. 몇 픽셀이 부족했습니다.</p> </li> <li> <p><strong>해결책:</strong>수술적인 간격 축소. 구식 CSS 해크를 이용해 파이어폭스를 특정적으로 타겟팅하는 것은 논외였기 때문에, 깨끗한 유일한 해결책은 어디서든 작동하는 공통 스타일을 찾는 것이었다. 따라서 각 탐색 링크의 여백과 수평 패딩을 약간 줄였습니다.</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">/* La version finale, légèrement plus compacte */ .navbar-nav .nav-link { font-size: 0.9rem; /* 90% de la taille de base */ color: var(--text-primary) !important; font-weight: 500; margin: 0 0.2rem; padding: 0.5rem 0.5rem !important; border-radius: 0.375rem; transition: all 0.3s ease; }</code></pre> </div> </div> <div class="paragraph"> <p>이 감소는 개별 요소에서 거의 눈에 띄지 않지만, Firefox에서 모든 링크가 프레임 안에 들어갈 수 있도록 필요한 공간을 collectively 확보하게 해주었으며, 다른 브라우저에서는 거의 동일한 외관을 유지합니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_문제_5_보이지_않는_햄버거_메뉴">문제 5 : 보이지 않는 햄버거 메뉴</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">마지막 문제였고, 작은 것이 아니었으며, 모바일 접근성과 관련이 있었습니다.</div> <ul> <li> <p><strong>증상 :</strong>응답형 메뉴(햄버거 메뉴) 모드에서는 'dark’와 'high-contrast' 테마에서 메뉴 아이콘이 보이지 않았습니다.</p> </li> <li> <p><strong>근본 원인 :</strong>Bootstrap 5 메뉴의 아이콘은`background-image`(URL로 인코딩된 SVG). 기본적으로, 선 색은 어둡고 밝은 배경에 최적화되어 있습니다. 테마 변경에 자동으로 적응하지 않습니다.</p> </li> <li> <p><strong>해결책 :</strong>Bootstrap CSS 변수를 사용하여 아이콘을 오버라이드합니다. 우리는 새로운 SVG 아이콘을 정의했지만, 이번엔 흰색 스트로크로 (<code>#ffffff</code>), 그리고 우리는 그것을 주제에 대해 구체적으로 적용했다`dark` ou `high-contrast`활동 중입니다.</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">/* ====================== Fix pour l'icône du menu Burger (Blanc) ====================== */ [data-bs-theme="dark"] .navbar-toggler-icon, [data-bs-theme="high-contrast"] .navbar-toggler-icon { --bs-navbar-toggler-icon-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 30 30'%3e%3cpath stroke='%23ffffff' stroke-linecap='round' stroke-miterlimit='10' stroke-width='2' d='M4 7h22M4 15h22M4 23h22'/%3e%3c/svg%3e"); }</code></pre> </div> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="Important"></i> </td> <td class="content"> <div class="paragraph"> <p>Bootstrap 구성 요소와 같은 것의 맞춤 설정은 CSS 변수 오버라이드를 통해 점점 더 많이 이루어지고 있습니다.<code>--bs-component-property</code>), 가장 깨끗하고 가장 지속 가능한 방법입니다.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_결론_끈질긴_디버깅의_교훈">결론 : 끈질긴 디버깅의 교훈</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 과정은 때때로 짜증나지만, 풍부한 교훈을 제공합니다. 해결된 모든 문제는 웹 개발의 근본적인 진리를 강화합니다:<strong>엄격한 다중 브라우저 테스트를 대체할 수 있는 것은 없습니다.</strong>.</p> </div> <div class="listingblock"> <div class="title">Mindmap : 디버깅과 배운 교훈 요약</div> <div class="content"> <pre>@startmindmap + Débogage Cross-Browser : Bootstrap 5 ++ **Conflit :** Chrome (Blink) vs Firefox (Gecko) ++ **Problème 1 : Alignement Hero** +++ Cause : Hauteur implicite +++ Solution : Classe `.h-100` ++ **Problème 2 : Navbar Cannibale** +++ Cause : "마법의 숫자" (padding fixe) +++ Solution : JS `offsetHeight` ++ **Problème 3 : Typographie Géante** +++ Cause : Rendu des `rem` +++ Solution : CSS `clamp()` ++ **Problème 4 : Menu qui déborde** +++ Cause : Calcul de largeur sub-pixel +++ Solution : Réduction des marges/paddings ++ **Problème 5 : Icône Invisible** +++ Cause : SVG non adaptable au thème +++ Solution : Surcharge de variable CSS ++ **Leçons Clés** +++ Firefox force un code robuste +++ Fuir les "마법 숫자" +++ Maîtriser la typographie fluide +++ Personnaliser via les variables CSS @endmindmap</pre> </div> </div> <div class="paragraph"> <p>우리가 기억하는 교훈은 다음과 같습니다:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Firefox는 협력자 :</strong>CSS 표준에 대한 가장 큰 충실함은 우리를 더 견고하고 덜 모호한 코드를 작성하도록 강요한다.</p> </li> <li> <p><strong>마법 수를 피하라 :</strong>고정된 값들 (예를 들어`padding-top: 80px`) 시한 폭탄입니다. 항상 동적인 솔루션(JavaScript) 또는 상대적인 솔루션(Flexbox, Grid)을 선호하세요.</p> </li> <li> <p><strong>타이포그래피를 마스터하세요 :</strong>사용하세요`clamp()`반응형 폰트 크기를 완전히 제어하기 위해.</p> </li> <li> <p><strong>구성 요소 단위로 생각하세요:</strong>Bootstrap을 커스터마이징하려면 프레임워크를 덮어쓰는 규칙을 늘리기보다 CSS 변수를 오버라이드하세요.</p> </li> <li> <p><strong>브라우저를 대상으로 삼지 마세요:</strong>해결책은 거의 특정 브라우저를 위한 \"해킹\"을 하는 것이 아니라, 어디서나 작동하는 공통된 스타일을 찾는 것입니다.</p> </li> </ol> </div> <div class="paragraph"> <p>최종적으로, 모형은 이제 견고하고 예측 가능하며, 템플릿 시스템에 통합할 준비가 되어 있습니다. 수정된 각 버그는 실패가 아니라 더 나은 코드로 나아가는 단계였습니다.</p> </div> </div> </div> https://cheroliv.com/blog/2025/0081_TDD_Gradle_Properties_Fix_post.html Sun, 13 Jul 2025 00:00:00 +0000 blog/2025/0081_TDD_Gradle_Properties_Fix_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_문제_gradle_플러그인의_단위_테스트_격리">문제 : Gradle 플러그인의 단위 테스트 격리</a> <ul class="sectlevel2"> <li><a href="#_문제_아키텍처">문제 아키텍처</a></li> <li><a href="#_거짓_좋은_아이디어의_유혹">거짓 좋은 아이디어의 유혹</a></li> </ul> </li> <li><a href="#_해결책_extrapropertiesextension를_사용해_속성을_시뮬레이션하기">해결책 : `ExtraPropertiesExtension`를 사용해 속성을 시뮬레이션하기</a> <ul class="sectlevel2"> <li><a href="#_1단계_extrapropertiesextension_이해하기">1단계: ExtraPropertiesExtension 이해하기</a></li> <li><a href="#_2단계_테스트_설정_준비">2단계: 테스트 설정 - 준비</a></li> <li><a href="#_단계_3_속성_주입">단계 3: 속성 주입</a></li> <li><a href="#_단계_4_솔루션_흐름도">단계 4: 솔루션 흐름도</a></li> <li><a href="#_단계_5_비교_전후">단계 5: 비교 전/후</a></li> <li><a href="#_단계_6_다중_테스트_사례_관리">단계 6 : 다중 테스트 사례 관리</a></li> <li><a href="#_솔루션의_최종_아키텍처">솔루션의 최종 아키텍처</a></li> </ul> </li> <li><a href="#_이_접근_방식의_장점">이 접근 방식의 장점</a></li> <li><a href="#_모범_사례와_조언">모범 사례와 조언</a> <ul class="sectlevel2"> <li><a href="#_유틸리티_메서드_생성">유틸리티 메서드 생성</a></li> <li><a href="#_속성_검증">속성 검증</a></li> </ul> </li> <li><a href="#_결론">결론</a></li> </ul> </div> <div class="sect1"> <h2 id="_문제_gradle_플러그인의_단위_테스트_격리">문제 : Gradle 플러그인의 단위 테스트 격리</h2> <div class="sectionbody"> <div class="paragraph"> <p>Gradle 플러그인에 대한 단위 테스트를 작성할 때 일반적인 도전 과제는 프로젝트 구성에 대한 의존성을 관리하는 것, 즉 파일에 정의된 속성과 같은 것`gradle.properties`. 우리의 경우, 플러그인`jbake.ghpages`속성을 읽어야 했다`site_config_path`올바르게 작동하기 위해. 작업을 위한 단위 테스트`initialize`이 속성이 존재할 때 플러그인의 동작을 확인해야 했다.</p> </div> <div class="paragraph"> <p>근본적인 문제는 단위 테스트가 설계상으로는 <strong>격리된</strong> 상태여야 한다는 것입니다. 사용하는 것은`ProjectBuilder`Gradle이 인스턴스를 생성합니다.<code>Project`메모리에서, 파일 시스템에 있는 실제 프로젝트와 완전히 연결되지 않은 상태입니다. 따라서 이 테스트 인스턴스는 파일을 자동으로 읽지 않습니다.`gradle.properties`그리고 따라서 그 속성에 대해 알지 못합니다.`site_config_path</code>.</p> </div> <div class="sect2"> <h3 id="_문제_아키텍처">문제 아키텍처</h3> <div class="paragraph"> <p>다음 다이어그램은 테스트 환경과 파일 시스템 사이의 분리 관계를 보여줍니다:</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml !define RECTANGLE class package "프로덕션 환경" { RECTANGLE ProjectReal { + build.gradle.kts + gradle.properties + src/ } RECTANGLE GradleProperties { site_config_path=src/jbake/settings/site.yml } RECTANGLE JbakePlugin { - readProperty(name: String) + initialize() } ProjectReal --> GradleProperties : lit au démarrage JbakePlugin --> GradleProperties : accède via project.properties } package "테스트 환경" { RECTANGLE ProjectTest { + Créé par ProjectBuilder + En mémoire uniquement + Pas de gradle.properties } RECTANGLE JbakePluginTest { + testInitialize() } ProjectTest -[#red]x GradleProperties : ❌ Pas d'accès JbakePluginTest --> ProjectTest : utilise } note right of ProjectTest : Isolation = Pas d'accès\nau système de fichiers @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_거짓_좋은_아이디어의_유혹">거짓 좋은 아이디어의 유혹</h3> <div class="paragraph"> <p>첫 번째 접근 방식은 파일을 생성하는 것일 수 있다.`gradle.properties`테스트 자원에서 가짜인</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">// src/test/resources/gradle.properties site_config_path=src/jbake/settings/site.yml</code></pre> </div> </div> <div class="paragraph"> <p>그러나, 이 방법은 실패를 피할 수 없는 운명이기 때문에`ProjectBuilder`설계된 것이 파일 시스템을 스캔하여 구성 파일을 찾는 것이 아니므로, 테스트는 격리된 상태로 남아 이 파일을 무시합니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_해결책_extrapropertiesextension를_사용해_속성을_시뮬레이션하기">해결책 : `ExtraPropertiesExtension`를 사용해 속성을 시뮬레이션하기</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 문제의 우아한 솔루션은 파일을 <strong>읽는</strong> 것이 아니라, 객체에 속성의 존재를 직접 <strong>시뮬레이션*하는 것이다.`Project`de 테스트. Gradle은 이를 위한 강력한 메커니즘을 제공합니다: *추가 속성</strong>(Extra Properties).</p> </div> <div class="sect2"> <h3 id="_1단계_extrapropertiesextension_이해하기">1단계: ExtraPropertiesExtension 이해하기</h3> <div class="paragraph"> <p>`ExtraPropertiesExtension`이는 Gradle 모델의 각 객체에 연결된 키-값 컨테이너입니다. 이를 통해 프로젝트, 태스크 또는 기타 Gradle 확장에 동적으로 속성을 추가할 수 있습니다.</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml !define RECTANGLE class RECTANGLE Project { + name: String + version: String + extensions: ExtensionContainer + properties: Map<String, ?> } RECTANGLE ExtensionContainer { + getByType(Class<T>): T + add(String, Object): void } RECTANGLE ExtraPropertiesExtension { + set(String, Object): void + get(String): Object + has(String): boolean + getProperties(): Map<String, Object> } Project --> ExtensionContainer : contient ExtensionContainer --> ExtraPropertiesExtension : gère ExtraPropertiesExtension --> Project : synchronise avec\nproject.properties note right of ExtraPropertiesExtension : Point d'entrée pour\ninjecter des propriétés @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_2단계_테스트_설정_준비">2단계: 테스트 설정 - 준비</h3> <div class="paragraph"> <p>먼저, 우리 단위 테스트의 기본 구조를 만들어봅시다 :</p> </div> <div class="listingblock"> <div class="title">JbakeGhPagesPluginTest.kt - Structure de base</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class JbakeGhPagesPluginTest { @TempDir lateinit var testProjectDir: File @Test fun `check initialize and config yaml file if not existing`() { // Étape 1 : Créer un projet de test isolé val project = ProjectBuilder.builder() .withProjectDir(testProjectDir) .build() // Suite des étapes... } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_단계_3_속성_주입">단계 3: 속성 주입</h3> <div class="paragraph"> <p>다음은 테스트 프로젝트에 속성을 삽입하는 상세한 과정입니다:</p> </div> <div class="listingblock"> <div class="title">JbakeGhPagesPluginTest.kt - Injection complète</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `check initialize and config yaml file if not existing`() { // Étape 1 : Créer un projet de test isolé en mémoire val project = ProjectBuilder.builder() .withProjectDir(testProjectDir) .build() // Étape 2 : Récupérer le gestionnaire de propriétés supplémentaires val extra = project.extensions.getByType(ExtraPropertiesExtension::class.java) // Étape 3 : Définir la propriété requise pour ce test extra.set("site_config_path", "src/jbake/settings/site.yml") // Étape 4 : Vérifier que la propriété est bien injectée assertTrue(project.hasProperty("site_config_path")) // Étape 5 : Appliquer le plugin qui pourra maintenant accéder à la propriété project.plugins.apply("jbake.ghpages") // Étape 6 : Exécuter la tâche et vérifier son comportement val task: Task = project.tasks.findByName("initialize") .apply(::assertNotNull)!! // Étape 7 : Exécuter les actions de la tâche task.actions.forEach { it.execute(task) } // Étape 8 : Assertions finales assertEquals( "src/jbake/settings/site.yml", project.properties["site_config_path"], "La propriété devrait être accessible dans le projet" ) }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_단계_4_솔루션_흐름도">단계 4: 솔루션 흐름도</h3> <div class="listingblock"> <div class="content"> <pre>@startuml start :Créer ProjectBuilder; :Obtenir ExtraPropertiesExtension; :Injecter la propriété\nvia extra.set(); partition "검사" { :Vérifier project.hasProperty(); :Appliquer le plugin; :Récupérer la tâche; } partition "실행" { :Exécuter les actions\nde la tâche; :Le plugin lit\nproject.properties; } partition "주장" { :Vérifier la propriété\nest accessible; :Valider le comportement\nattendues; } stop @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_단계_5_비교_전후">단계 5: 비교 전/후</h3> <div class="listingblock"> <div class="content"> <pre>@startuml !define RECTANGLE class package "이전 - 문제" { RECTANGLE TestProject1 { + ProjectBuilder.build() + Pas de propriétés } RECTANGLE Plugin1 { + initialize() + ❌ project.properties["사이트_설정_경로"] = null } TestProject1 --> Plugin1 : échec note right of Plugin1 : Test échoue car\nla propriété n'existe pas } package "후 - 해결책" { RECTANGLE TestProject2 { + ProjectBuilder.build() + ExtraPropertiesExtension } RECTANGLE ExtraProps { + set("사이트_설정_경로", "...") } RECTANGLE Plugin2 { + initialize() + ✅ project.properties["사이트_설정_경로"] = "src/jbake/settings/site.yml" } TestProject2 --> ExtraProps : configure ExtraProps --> Plugin2 : propriété disponible note right of Plugin2 : Test réussit car\nla propriété est simulée } @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_단계_6_다중_테스트_사례_관리">단계 6 : 다중 테스트 사례 관리</h3> <div class="paragraph"> <p>다양한 시나리오를 테스트하기 위해 다양한 구성의 여러 테스트를 만들어 봅시다 :</p> </div> <div class="listingblock"> <div class="title">Tests multiples avec configurations différentes</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class JbakeGhPagesPluginTest { @TempDir lateinit var testProjectDir: File private fun createProjectWithProperty(propertyValue: String?): Project { val project = ProjectBuilder.builder() .withProjectDir(testProjectDir) .build() // Injection conditionnelle de la propriété propertyValue?.let { value -> val extra = project.extensions.getByType(ExtraPropertiesExtension::class.java) extra.set("site_config_path", value) } return project } @Test fun `should work with valid property`() { val project = createProjectWithProperty("src/jbake/settings/site.yml") project.plugins.apply("jbake.ghpages") val task = project.tasks.findByName("initialize")!! task.actions.forEach { it.execute(task) } // Assertions pour le cas normal assertEquals("src/jbake/settings/site.yml", project.properties["site_config_path"]) } @Test fun `should handle missing property gracefully`() { val project = createProjectWithProperty(null) // Pas de propriété project.plugins.apply("jbake.ghpages") val task = project.tasks.findByName("initialize")!! // Le plugin devrait gérer l'absence de propriété assertDoesNotThrow { task.actions.forEach { it.execute(task) } } } @Test fun `should handle invalid property path`() { val project = createProjectWithProperty("invalid/path/to/config.yml") project.plugins.apply("jbake.ghpages") val task = project.tasks.findByName("initialize")!! // Test du comportement avec un chemin invalide assertThrows<FileNotFoundException> { task.actions.forEach { it.execute(task) } } } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_솔루션의_최종_아키텍처">솔루션의 최종 아키텍처</h3> <div class="listingblock"> <div class="content"> <pre>@startuml !define RECTANGLE class package "테스트 환경" { RECTANGLE TestClass { + createProjectWithProperty() + testValidProperty() + testMissingProperty() + testInvalidProperty() } RECTANGLE ProjectBuilder { + builder() + withProjectDir() + build() } RECTANGLE TestProject { + extensions + properties + plugins + tasks } RECTANGLE ExtraPropertiesExtension { + set(key, value) + get(key) + has(key) } RECTANGLE JbakePlugin { + apply(project) + createInitializeTask() + readSiteConfigPath() } } TestClass --> ProjectBuilder : utilise ProjectBuilder --> TestProject : crée TestProject --> ExtraPropertiesExtension : contient TestClass --> ExtraPropertiesExtension : configure ExtraPropertiesExtension --> TestProject : synchronise properties TestProject --> JbakePlugin : applique JbakePlugin --> TestProject : lit properties note right of ExtraPropertiesExtension : Point de contrôle\npour l'injection note bottom of TestProject : Environnement\ncontrôlé et isolé @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_이_접근_방식의_장점">이 접근 방식의 장점</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><strong>완전 절연</strong>테스트는 외부 파일에 의존하지 않습니다. 독립적이며, 로컬, CI/CD 등을 포함한 어떤 환경에서도 신뢰성 있게 실행할 수 있습니다.</p> </li> <li> <p><strong>명확함과 의도</strong>테스트는 실행에 필요한 선행 조건을 명시적으로 선언합니다. 테스트를 읽는 사람은 누구든 플러그인이 해당 속성을 필요로 한다는 것을 즉시 알 수 있다.`site_config_path`작동하기 위해.</p> </li> <li> <p><strong>유지보수성</strong>속성 이름이 변경되면 테스트에서 한 곳만 업데이트하면 되고, 테스트 구성 파일을 수정할 필요가 없습니다.</p> </li> <li> <p><strong>유연성</strong>: 각 테스트에서 주입된 속성 값을 단순히 바꾸는 것만으로도 다양한 시나리오를 테스트하는 것이 간단해집니다. (유효한 값, 무효한 값, 누락된 값 등)</p> </li> <li> <p><strong>퍼포먼스</strong>파일을 읽지 않으며, 모든 것이 메모리에서 이루어지므로 테스트가 더 빨라집니다.</p> </li> <li> <p><strong>재현성</strong>테스트는 파일 시스템의 상태에 의존하지 않기 때문에 결정적입니다.</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_모범_사례와_조언">모범 사례와 조언</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_유틸리티_메서드_생성">유틸리티 메서드 생성</h3> <div class="listingblock"> <div class="title">Méthode utilitaire pour la réutilisation</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class GradleTestUtils { companion object { fun createProjectWithProperties( projectDir: File, properties: Map<String, String> ): Project { val project = ProjectBuilder.builder() .withProjectDir(projectDir) .build() val extra = project.extensions.getByType(ExtraPropertiesExtension::class.java) properties.forEach { (key, value) -> extra.set(key, value) } return project } } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_속성_검증">속성 검증</h3> <div class="listingblock"> <div class="title">Validation robuste</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `should validate property injection`() { val project = createProjectWithProperty("test-value") // Vérifications multiples assertTrue(project.hasProperty("site_config_path")) assertEquals("test-value", project.property("site_config_path")) assertNotNull(project.properties["site_config_path"]) // Vérification que la propriété est accessible par le plugin project.plugins.apply("jbake.ghpages") // ... reste du test }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_결론">결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>단위 테스트 환경이 구성 파일을 읽도록 애쓰는 대신, 필요한 상태를 시뮬레이션하는 것이 모범 사례입니다. 사용`ExtraPropertiesExtension`프로그래밍 방식으로 Gradle 속성을 정의하는 것이 효율적이고 신뢰할 수 있는 플러그인 단위 테스트를 수행하는 가장 깔끔하고 견고한 방법입니다.</p> </div> <div class="paragraph"> <p>이 기술은 외부 의존성 문제를 간단한 의존성 주입으로 변환하여 테스트 주도 개발(TDD)의 철학 그 자체에 심어줍니다. 이 기술은 테스트 환경에 대한 완전한 제어를 제공하면서도 고품질 단위 테스트에 필요한 격리를 유지합니다.</p> </div> <div class="paragraph"> <p>이 기사에 제시된 다이어그램과 예시는 이 접근 방식을 점진적이고 체계적으로 구현하는 방법을 보여주며, 이를 통해 Gradle 플러그인을 위한 견고하고 유지 관리 가능한 테스트 제품군을 만들 수 있습니다.</p> </div> </div> </div> https://cheroliv.com/blog/2025/0079_gradle_tasks_tests_report_post.html Fri, 11 Jul 2025 00:00:00 +0000 blog/2025/0079_gradle_tasks_tests_report_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_allprojects와_subprojects를_사용하여_configurations을_중앙_집중화하세요">allprojects`와 `subprojects`를 사용하여 Configurations을 중앙 집중화하세요</a></li> <li><a href="#_sourceplantuml">[source,plantuml]</a></li> <li><a href="#_enduml">@enduml</a></li> <li><a href="#_sourcekotlin">[source,kotlin]</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>빌드 작업 자동화는 모든 소프트웨어 프로젝트에 매우 중요하며, Gradle의 Kotlin DSL을 사용하면 뛰어난 유연성을 제공합니다. 우리의 대화 중에, 우리는 빌드 로직을 중앙화하고 재사용하는 방법을 탐구했으며, 특히 테스트 보고서에 이를 활용하여<strong>모든 프로젝트</strong>, <strong>buildSrc</strong>, 그리고 코틀린에서의 맞춤형 작업.</p> </div> </div> </div> <div class="sect1"> <h2 id="_allprojects와_subprojects를_사용하여_configurations을_중앙_집중화하세요">allprojects`와 `subprojects`를 사용하여 Configurations을 중앙 집중화하세요</h2> <div class="sectionbody"> <div class="paragraph"> <p>블록들`allprojects` et `subprojects`당신의`build.gradle.kts`루트는 여러 모듈 프로젝트 전반에 걸쳐 공통 구성을 적용하는 데 기본적입니다.</p> </div> <div class="paragraph"> <p>*<code>allprojects { …​ }</code>: 구성을 적용<strong>루트 프로젝트 및 모든 하위 프로젝트</strong>. 정의하기에 좋은`group`, 하나의`version`, 또는`repositories`공통의. *<code>subprojects { …​ }`구성을 적용<strong>하위 프로젝트에만</strong>, 루트 프로젝트를 제외하고. 모듈에 특정한 플러그인을 적용하기에 완벽함 (예`java</code> ou <code>kotlin-jvm</code>) 또는 라이브러리에 공통된 종속성</p> </div> <div class="paragraph"> <p>다음은 예시입니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// build.gradle.kts (projet racine) plugins { base // Appliqué au projet racine } allprojects { group = "com.example" version = "1.0.0" repositories { mavenCentral() } tasks.withType<org.gradle.api.tasks.testing.Test> { useJUnitPlatform() // Configuration commune des tests pour tous les projets } } subprojects { apply(plugin = "java") apply(plugin = "org.jetbrains.kotlin.jvm") dependencies { implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8") } }</code></pre> </div> </div> <div class="paragraph"> <p>\==<code>buildSrc</code>: 빌드 로직의 스위스 군용 칼</p> </div> <div class="paragraph"> <p>작업의 로직이 복잡해지거나 재사용해야 할 때,<strong>buildSrc</strong>선호되는 솔루션입니다. 이는 주요 빌드 스크립트보다 먼저 컴파일되는 특수 Gradle 모듈이며, 이는 모든 빌드의 클래스패스에서 해당 클래스를 사용할 수 있게 합니다.</p> </div> <div class="paragraph"> <p>왜 사용하나요?`buildSrc`작업을 위해?</p> </div> <div class="ulist"> <ul> <li> <p><strong>재사용성</strong>정의된 작업 안에`buildSrc`해당 빌드의 모든 프로젝트에 적용할 수 있습니다.</p> </li> <li> <p><strong>조직</strong>빌드 코드를 중앙 집중화하여 더 깔끔하고 유지보수하기 쉽게 만든다.</p> </li> <li> <p><strong>타입 안전성과 자동 완성</strong>: Kotlin 코드 안의`buildSrc`컴파일되어 IDE의 오류 검사와 자동완성을 제공하여 개발 경험을 향상시킵니다.</p> </li> </ul> </div> <div class="paragraph"> <p>흐름도`buildSrc`(PlantUML 코드)</p> </div> <div class="paragraph"> <p>이 다이어그램을 생성하려면 아래 코드를 복사하고 PlantUML을 지원하는 도구에 붙여넣으세요.</p> </div> </div> </div> <div class="sect1"> <h2 id="_sourceplantuml">[source,plantuml]</h2> <div class="sectionbody"> <div class="paragraph"> <p>@startuml skinparam handwritten true skinparam monochrome true</p> </div> <div class="paragraph"> <p>rectangle "Gradle 빌드 프로세스" { component "buildSrc" as BS { file "MyCustomTask.kt" as T file "MyConventionPlugin.kt" as P } 컴포넌트 "Root Project"으로서 RP 컴포넌트 "Subproject A"를 SA로 구성요소 "Subproject B"를 SB로 }</p> </div> <div class="paragraph"> <p>T --\> P : "정의됨 P --\> RP : "적용됨 P --\> SA : "적용됨 P --\> SB : "적용됨</p> </div> <div class="paragraph"> <p>RP --|\> SA : "contains RP --|\> SB : "contains</p> </div> <div class="paragraph"> <p>RP -up-\> BS : "빌드 로직을 위해 의존함 SA -up→ BS : "의존 (빌드 로직을 위한) SB -up-\> BS : "depends on (for build logic)</p> </div> <div class="paragraph"> <p>T 오른쪽에 메모 커스텀 작업 클래스 (예: OpenTestReportTask) 끝 노트</p> </div> <div class="paragraph"> <p>P 오른쪽의 메모 협약 플러그인 작업을 기록하는 미주</p> </div> </div> </div> <div class="sect1"> <h2 id="_enduml">@enduml</h2> <div class="sectionbody"> <div class="paragraph"> <p>\== 추상 보고서 작업 생성</p> </div> <div class="paragraph"> <p>테스트 보고서를 관리하기 위해 우리는 모듈식 접근 방식을 설계했습니다 추상 작업 클래스를 사용하여 안에서`buildSrc`. 귀하의 필요에 따라 이 클래스는 상속받을 수 있습니다`DefaultTask` ou de <code>Exec</code>.</p> </div> <div class="paragraph"> <p>\=== 추상적 작업`OpenTestReportTask`(상속받는`DefaultTask`)</p> </div> <div class="paragraph"> <p>파일 시스템이나 다른 Gradle API와 상호작용하는 맞춤 Kotlin 로직이 필요한 경우 이 접근 방식을 사용하는 것이 권장됩니다. 그런 다음 외부 명령을 실행합니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_sourcekotlin">[source,kotlin]</h2> <div class="sectionbody"> <div class="paragraph"> <p>패키지 com.yourpackage</p> </div> <div class="paragraph"> <p>import org.gradle.api.DefaultTask 가져오기 org.gradle.api.tasks.Input import org.gradle.api.tasks.TaskAction import java.io.File</p> </div> <div class="paragraph"> <p>추상 클래스 OpenTestReportTask : DefaultTask()</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- ---- init { group = "verification" description = "Opens a test report in Firefox." dependsOn("check") // Assure que les rapports sont générés } @get:Input abstract var reportPath: String @TaskAction fun openReport() { val separator = File.separator val reportFile = project.layout.projectDirectory.asFile.toPath() .resolve(reportPath.replace("/", separator)) .toAbsolutePath() .toFile() if (!reportFile.exists()) { logger.warn("Report file does not exist: $reportFile. Ensure 'check' ran.") return } project.exec { commandLine("firefox", "--new-tab", reportFile.absolutePath) } logger.lifecycle("Opened test report: ${reportFile.absolutePath}") } ---- ## } 구체적인 구현 이 클래스들은 추상 작업을 상속받고 보고서의 특정 경로를 정의합니다. ## [source,kotlin] 패키지 com.yourpackage 추상 클래스 ReportUnitTestsTask : OpenTestReportTask() init { Firefox에서 단위 테스트 보고서를 엽니다. reportPath = "build/reports/tests/test/index.html } } 패키지 com.yourpackage ## abstract class ReportFunctionalTestsTask : OpenTestReportTask() { init { description = "파이어폭스에서 기능 테스트 보고서를 엽니다." reportPath = "build/reports/tests/functionalTest/index.html" } } \=== 작업 기록 안에`build.gradle.kts`당신의 루트 프로젝트: ## [source,kotlin] tasks.register<com.yourpackage.ReportUnitTestsTask>("reportTests") {} tasks.register<com.yourpackage.ReportFunctionalTestsTask>("reportFunctionalTests") {} \=== 보고서 작업의 UML 다이어그램 (PlantUML 코드) 아래 코드를 복사하여 PlantUML을 지원하는 도구에 붙여넣으세요. ## [source,plantuml] @startuml skinparam handwritten true skinparam 단색 true 추상 클래스 DefaultTask { } 추상 클래스 Exec { \+ commandLine(args: String...) \+ exec() } 추상 클래스 OpenTestReportTask 확장 DefaultTask { \+ group: String = "검증 \+ 설명: 문자열 \+ dependsOn("check") \+ abstract reportPath: String \+ openReport() : void } 추상 클래스 AbstractJbakeExecTask는 Exec를 확장합니다 { \+ group: String = "검증 \+ 설명: 문자열 \+ dependsOn("check") \+ 추상 보고상대경로: 문자열 \+ exec() : void } 클래스 ReportUnitTestsTask는 OpenTestReportTask를 확장합니다 { \+ reportPath: String = "build/reports/tests/test/index.html } 클래스 ReportFunctionalTestsTask extends OpenTestReportTask { \+ reportPath: String = "build/reports/tests/functionalTest/index.html } class ReportJbakeTestsTask extends AbstractJbakeExecTask { \+ reportRelativePath: String = "build/reports/tests/test/index.html } class ReportJbakeFunctionalTestsTask extends AbstractJbakeExecTask { \+ reportRelativePath: String = "build/reports/tests/functionalTest/index.html } OpenTestReportTask \<-- ReportUnitTestsTask OpenTestReportTask \<-- ReportFunctionalTestsTask AbstractJbakeExecTask \<-- ReportJbakeTestsTask AbstractJbakeExecTask \<-- ReportJbakeFunctionalTestsTask DefaultTask \<|-- OpenTestReportTask Exec \<|-- AbstractJbakeExecTask DefaultTask \<|-- Exec ## @enduml \== 추상적인 작업`AbstractJbakeExecTask`(상속받는`Exec`) 주로 외부 명령에 변수 인자를 실행하는 작업이라면, 직접 상속받는**실행**더 직접적입니다. ## [source,kotlin] 패키지 com.yourpackage import org.gradle.api.tasks.Exec import org.gradle.api.tasks.Input import java.io.File 추상 클래스 AbstractJbakeExecTask : Exec() { ---- init { group = "verification" description = "Opens a Jbake project report in Firefox." dependsOn("check") } @get:Input abstract var reportRelativePath: String override fun exec() { val separator = File.separator val reportFile = project.layout.projectDirectory.asFile.toPath() .resolve(reportRelativePath.replace("/", separator)) .toAbsolutePath() .toFile() if (!reportFile.exists()) { logger.warn("Report file does not exist: $reportFile. Ensure 'check' ran.") return } commandLine("firefox", "--new-tab", reportFile.absolutePath) logger.lifecycle("Attempting to open report: ${reportFile.absolutePath}") super.exec() // Appelle la méthode exec() de la super-classe Exec } ## } \=== 구체적인 구현을 위한`Exec` ## [source,kotlin] package com.yourpackage 추상 클래스 ReportJbakeTestsTask : AbstractJbakeExecTask() { init { description = "Firefox에서 Jbake 단위 테스트 보고서를 엽니다. reportRelativePath = "build/reports/tests/test/index.html } } package com.yourpackage abstract class ReportJbakeFunctionalTestsTask : AbstractJbakeExecTask() { init { description = "파이어폭스에서 기능 테스트 보고서를 엽니다." reportRelativePath = "build/reports/tests/functionalTest/index.html" } } \== 작업 가시성`buildSrc` 당신이 정의하는 작업 및 클래스는**buildSrc**이다 : ***보이고 사용 가능한**votre 메인 빌드의 모든 프로젝트(루트 및 하위 프로젝트)에서. 따라서 사용할 수 있습니다`com.yourpackage.ReportUnitTestsTask`안에`allprojects { ... }`. ***실행 불가능한**직접 buildSrc 작업으로서 (예를 들어,`gradle :buildSrc:reportTests`작업이 특정하게 기록되지 않으면 작동하지 않을 것입니다`buildSrc/build.gradle.kts`).`buildSrc`컴파일 모듈일 뿐, 이 메인 빌드 작업에 사용되는 실행 가능한 애플리케이션 모듈이 아닙니다. 테스트를 위한 보고서 실행`buildSrc`자기 Si `buildSrc`자신만의 테스트를 수행하고 보고서를 생성하면, 보고 작업을 직접 기록할 수 있습니다`buildSrc/build.gradle.kts`: ## [source,kotlin] plugins { `kotlin-jvm` } 저장소 { mavenCentral() } tasks.withType\<Test\> { useJUnitPlatform() 보고서.html.출력위치.set(레이아웃.빌드디렉터리.dir("보고서/테스트")) } import com.yourpackage.ReportJbakeTestsTask // 작업 클래스를 가져옵니다 tasks.register\<ReportJbakeTestsTask\>("reportBuildSrcTests") { // Le chemin est déjà défini dans la classe, il pointera vers les rapports de buildSrc } 그 다음에 실행할 수 있습니다 :`./gradlew :buildSrc:test`다음에`./gradlew :buildSrc:reportBuildSrcTests`. 이러한 관행을 채택함으로써 Kotlin DSL을 사용한 Gradle 빌드 시스템을 구축하게 되며, 이는 단순히 강력할 뿐만 아니라 놀랍도록 모듈화 가능하고 유지 보수가 쉬우며 이해하기 쉽습니다.</code></pre> </div> </div> </div> </div> https://cheroliv.com/blog/2025/0078_jbake_gradle_plugin_syntaxe_post.html Wed, 9 Jul 2025 00:00:00 +0000 blog/2025/0078_jbake_gradle_plugin_syntaxe_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_목표">목표</a></li> <li><a href="#_선언적_구성">선언적 구성</a></li> <li><a href="#_플러그인_아키텍처">플러그인 아키텍처</a></li> <li><a href="#_dsl_확장_정의">DSL 확장 정의</a></li> <li><a href="#_사용자_지정_작업의_정의">사용자 지정 작업의 정의</a></li> <li><a href="#_인터페이스_gitadapter">인터페이스 GitAdapter</a></li> <li><a href="#_jgit을_사용한_구체적인_구현">JGit을 사용한 구체적인 구현</a></li> <li><a href="#_kotlin_dsl_구성">Kotlin DSL 구성</a></li> <li><a href="#_mockito를_사용한_단위_테스트">Mockito를 사용한 단위 테스트</a> <ul class="sectlevel2"> <li><a href="#_의존성">의존성</a></li> <li><a href="#_git_동작_테스트">Git 동작 테스트</a></li> </ul> </li> <li><a href="#_결론">결론</a></li> <li><a href="#_다음_단계">다음 단계</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>이 글은 Kotlin DSL로 작성된 Gradle 플러그인의 설계 및 테스트(TDD) 전체 과정을 소개합니다. 이 플러그인은 *JBake*를 사용한 정적 사이트 생성과 *JGit*을 통한 *Git 배포*를 자동화하며, 모든 것이 구성 YAML 파일에서 시작됩니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_목표">목표</h2> <div class="sectionbody"> <div class="paragraph"> <p>Gradle 플러그인 만들기 :</p> </div> <div class="ulist"> <ul> <li> <p>Kotlin DSL에서 설정 가능;</p> </li> <li> <p>할 수 있는 :</p> </li> <li> <p>JBake에서 정적 사이트 생성 ;</p> </li> <li> <p>원격 Git 저장소에 JGit을 통해 배포 ;</p> </li> <li> <p>CI/CD 워크플로에 통합 가능한 ;</p> </li> <li> <p>TDD 방법론에 따라 테스트된</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_선언적_구성">선언적 구성</h2> <div class="sectionbody"> <div class="paragraph"> <p>다음은 우리 DSL에서 모델링할 YAML 구성의 예시 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">bake: srcPath: "./site/jbake" destDirPath: "bake" pushPage: from: "bake" to: "cvs" repo: name: "trainings" repository: "https://github.com/pages-content/trainings.git" credentials: username: "USERNAME" password: "SECRET_TOKEN" branch: "main" message: "cheroliv.com"</code></pre> </div> </div> <div class="paragraph"> <p>이 구성은 Kotlin DSL에서 선언 가능한 Gradle 확장을 통해 표현됩니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_플러그인_아키텍처">플러그인 아키텍처</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>@startuml package "엔진-플러그인" { class WorkspaceEngineExtension class GenerateSiteTask interface GitAdapter class JGitAdapter WorkspaceEnginePlugin --> WorkspaceEngineExtension WorkspaceEnginePlugin --> GenerateSiteTask GenerateSiteTask --> GitAdapter JGitAdapter ..|> GitAdapter } @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_dsl_확장_정의">DSL 확장 정의</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">open class WorkspaceEngineExtension { var outputDir: String = "build/site" var template: String = "freemarker" var repoUrl: String = "" var branch: String = "main" var message: String = "Generated by engine" }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_사용자_지정_작업의_정의">사용자 지정 작업의 정의</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">abstract class GenerateSiteTask : DefaultTask() { lateinit var gitAdapter: GitAdapter @get:Input abstract val repoUrl: Property<String> @get:InputDirectory abstract val outputDir: DirectoryProperty @get:Input abstract val branch: Property<String> @get:Input abstract val message: Property<String> @TaskAction fun run() { val repo = gitAdapter.cloneRepository(repoUrl.get(), outputDir.get().asFile) gitAdapter.commitAndPush(repo, branch.get(), message.get()) } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_인터페이스_gitadapter">인터페이스 GitAdapter</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">interface GitAdapter { fun cloneRepository(uri: String, directory: File): Repository fun commitAndPush(repo: Repository, branch: String, message: String) }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_jgit을_사용한_구체적인_구현">JGit을 사용한 구체적인 구현</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class JGitAdapter : GitAdapter { override fun cloneRepository(uri: String, directory: File): Repository { return Git.cloneRepository() .setURI(uri) .setDirectory(directory) .call() .repository } override fun commitAndPush(repo: Repository, branch: String, message: String) { Git(repo).use { it.add().addFilepattern(".").call() it.commit().setMessage(message).call() it.push().call() } } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_kotlin_dsl_구성">Kotlin DSL 구성</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">workspaceEngine { outputDir = "build/out" template = "freemarker" repoUrl = "https://github.com/cheroliv/trainings.git" branch = "main" message = "deploy from plugin" }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_mockito를_사용한_단위_테스트">Mockito를 사용한 단위 테스트</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_의존성">의존성</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">testImplementation("org.mockito:mockito-core:5.12.0") testImplementation("org.mockito.kotlin:mockito-kotlin:5.2.1") testImplementation("org.junit.jupiter:junit-jupiter:5.10.0")</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_git_동작_테스트">Git 동작 테스트</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class GenerateSiteTaskMockitoTest { @TempDir lateinit var tempDir: File @Test fun `task should call clone and commitAndPush`() { val project = ProjectBuilder.builder().build() val task = project.tasks.create("generateSite", GenerateSiteTask::class.java) val mockGitAdapter = mock<GitAdapter>() val mockRepo = mock<Repository>() whenever(mockGitAdapter.cloneRepository(any(), any())).thenReturn(mockRepo) task.gitAdapter = mockGitAdapter task.repoUrl.set("https://github.com/cheroliv/test.git") task.outputDir.set(project.layout.projectDirectory.dir(tempDir.name)) task.branch.set("main") task.message.set("test commit") task.run() verify(mockGitAdapter).cloneRepository(eq("https://github.com/cheroliv/test.git"), any()) verify(mockGitAdapter).commitAndPush(eq(mockRepo), eq("main"), eq("test commit")) } }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre>@startuml actor "개발자" as Dev participant "Gradle 프로젝트 빌더" as Project participant "생성사이트작업" as Task participant "GitAdapter (모의)" as Adapter participant "JGitAdapter / Mockito" as Impl Dev -> Project : construit projet Gradle Dev -> Task : configure les propriétés Task -> Adapter : cloneRepository() Adapter -> Impl : simulé par Mockito Task -> Adapter : commitAndPush() @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_결론">결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>책임의 분리 via`GitAdapter`Gradle 플러그인 개발에서 TDD를 완전히 적용할 수 있도록 해줍니다:</p> </div> <div class="ulist"> <ul> <li> <p>Git 호출은 추상화되고 테스트 가능합니다;</p> </li> <li> <p>DSL 구성은 깔끔하고 명확합니다;</p> </li> <li> <p>플러그인은 실제 구현에 대해 중립적이다.</p> </li> </ul> </div> <div class="paragraph"> <p>이 접근 방식은 높은 테스트 가능성과 확장성(GitHub API, GitLab 등)을 보장합니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_다음_단계">다음 단계</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>JBake 생성을 통합하는`BakeAdapter`</p> </li> <li> <p>통합 테스트 추가하기`GradleRunner`</p> </li> <li> <p>자동 파일 로드 지원`site.yml`SnakeYAML을 통해</p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2025/0077_asciidoc_syntaxe_post.html Fri, 20 Jun 2025 00:00:00 +0000 blog/2025/0077_asciidoc_syntaxe_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_서론">서론</a></li> <li><a href="#_asciidoc이란_무엇인가요">AsciiDoc이란 무엇인가요?</a> <ul class="sectlevel2"> <li><a href="#_왜_asciidoc을_선택해야_하나요">왜 AsciiDoc을 선택해야 하나요?</a></li> </ul> </li> <li><a href="#_유스케이스_다이어그램_use_case">유스케이스 다이어그램 (Use Case)</a></li> <li><a href="#_마인드_맵_다이어그램">마인드 맵 다이어그램</a></li> <li><a href="#_흐름도_플럭스">흐름도 (플럭스)</a></li> <li><a href="#_asciidoc_파일의_기본_구조">AsciiDoc 파일의 기본 구조</a></li> <li><a href="#_기본_구문">기본 구문</a> <ul class="sectlevel2"> <li><a href="#_제목과_섹션">제목과 섹션</a></li> <li><a href="#_진하게_표시된_텍스트_기울임_꼴_고정폭_글꼴">진하게 표시된 텍스트, 기울임 꼴, 고정폭 글꼴</a></li> <li><a href="#_불릿_목록_및_번호가_매긴_목록">불릿 목록 및 번호가 매긴 목록</a></li> <li><a href="#_링크와_이미지">링크와 이미지</a></li> <li><a href="#_코드_블록">코드 블록</a></li> <li><a href="#_표">표</a></li> <li><a href="#_주석_및_경고">주석 및 경고</a></li> </ul> </li> <li><a href="#_속성_및_변수_사용">속성 및 변수 사용</a></li> <li><a href="#_일반적인_사용_사례">일반적인 사용 사례</a></li> <li><a href="#_모범_사례">모범 사례</a></li> <li><a href="#_결론">결론</a></li> <li><a href="#_더_나아가기">더 나아가기</a></li> </ul> </div> <div class="sect1"> <h2 id="_서론">서론</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title"><em>대상 :</em> 개발자, 기술 작성자, 그리고 기술 문서나 풍부한 기사 작성을 원하는 모든 사람.</div> <p>AsciiDoc은 구조화된 기술 문서, 기사, 책 또는 프레젠테이션을 작성하기 위해 설계된 경량 마크업 언어입니다. 가독성, 풍부한 문법 및 HTML, PDF, DocBook 등 다양한 포맷을 생성할 수 있는 능력으로 두드러집니다. 이 글에서는 AsciiDoc의 필수 구문을 탐색하고 빠르게 시작할 수 있는 팁을 제시하겠습니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_asciidoc이란_무엇인가요">AsciiDoc이란 무엇인가요?</h2> <div class="sectionbody"> <div class="paragraph"> <p>AsciiDoc는 문서 설명 언어이며, Markdown과 비슷하지만 더 강력합니다. 텍스트, 제목, 목록, 표, 코드 블록 등을 효율적으로 구조화할 수 있습니다. 그 다재다능함 덕분에 오픈 소스 프로젝트 문서화, 저서 작성, 웹 출판에 인기 있는 선택이 됩니다.</p> </div> <div class="sect2"> <h3 id="_왜_asciidoc을_선택해야_하나요">왜 AsciiDoc을 선택해야 하나요?</h3> <div class="olist arabic"> <ol class="arabic"> <li> <p>읽기 쉬우면서 직관적인 구문</p> </li> <li> <p>복잡한 구조(표, 주석, 경고 등)의 네이티브 지원.</p> </li> <li> <p>멀티 형식 생성 (HTML, PDF, ePub, DocBook…)</p> </li> <li> <p>JBake 또는 Antora와 같은 정적 사이트 생성기와 쉽게 통합.</p> </li> <li> <p>속성과 확장을 사용한 고급 사용자 지정.</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_유스케이스_다이어그램_use_case">유스케이스 다이어그램 (Use Case)</h2> <div class="sectionbody"> <div class="paragraph"> <p>유스케이스 다이어그램은 사용자와 시스템 간의 주요 상호작용을 보여줍니다. 다음은 문서화 시스템을 위한 간단한 예시입니다:</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml :Utilisateur: --> (Rédiger documentation) :Utilisateur: --> (Générer PDF) :Utilisateur: --> (Publier sur site web) (Rédiger documentation) ..> (Générer PDF) : inclut @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_마인드_맵_다이어그램">마인드 맵 다이어그램</h2> <div class="sectionbody"> <div class="paragraph"> <p>마인드 맵(마인드맵)은 AsciiDoc과 관련된 개념을 탐색하고 그 관계를 파악하기에 적합합니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre>@startmindmap * AsciiDoc ** Syntaxe *** Titres *** Listes *** Blocs de code *** Tableaux ** Extensions *** PlantUML *** MathJax ** Export *** HTML *** PDF *** EPUB @endmindmap</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_흐름도_플럭스">흐름도 (플럭스)</h2> <div class="sectionbody"> <div class="paragraph"> <p>플로우 다이어그램은 AsciiDoc 문서 생성 과정을 설명할 수 있습니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre>@startuml start :Écrire fichier .adoc; :Ajouter images et diagrammes; if (Valider la syntaxe ?) then (oui) :Générer HTML/PDF; :Publier ou partager; else (non) :Corriger erreurs; :back to start; endif stop @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_asciidoc_파일의_기본_구조">AsciiDoc 파일의 기본 구조</h2> <div class="sectionbody"> <div class="paragraph"> <p>AsciiDoc 파일은 일반적으로 제목으로 시작하고, 선택적 속성이 뒤이어 오며, 그 다음 구조화된 콘텐츠가 옵니다. 다음은 최소한의 예시:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Titre Principal Auteur 2024-09-03 :toc: :icons: font Votre contenu commence ici...</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_기본_구문">기본 구문</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_제목과_섹션">제목과 섹션</h3> <div class="paragraph"> <p>AsciiDoc은 여러 수준의 제목을 지원합니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Titre de niveau 1 == Titre de niveau 2 === Titre de niveau 3 ==== Titre de niveau 4</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_진하게_표시된_텍스트_기울임_꼴_고정폭_글꼴">진하게 표시된 텍스트, 기울임 꼴, 고정폭 글꼴</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">*gras* _italique_ `monospace`</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_불릿_목록_및_번호가_매긴_목록">불릿 목록 및 번호가 매긴 목록</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* Élément 1 * Élément 2 . Premier . Deuxième . Troisième</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_링크와_이미지">링크와 이미지</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">Lien standard : https://asciidoc.org[AsciiDoc] Image : image::images/logo.png[AsciiDoc Logo]</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_코드_블록">코드 블록</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">[source,python]</code></pre> </div> </div> <div class="paragraph"> <p>def hello(): print("안녕 AsciiDoc!")</p> </div> </div> <div class="sect2"> <h3 id="_표">표</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">|=== | Colonne 1 | Colonne 2 | Valeur A | Valeur B | Valeur C | Valeur D |===</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_주석_및_경고">주석 및 경고</h3> <div class="paragraph"> <p>AsciiDoc은 시각 정보 블록을 제공합니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">NOTE: Ceci est une note importante. TIP: Conseil utile pour l’utilisateur. WARNING: Attention à ce point.</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_속성_및_변수_사용">속성 및 변수 사용</h2> <div class="sectionbody"> <div class="paragraph"> <p>사용자 지정 속성을 사용하면 값을 재사용하거나 동작을 구성할 수 있습니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">:project-name: AsciiDoc Explorer Le projet s’appelle {project-name}.</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_일반적인_사용_사례">일반적인 사용 사례</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>오픈 소스 프로젝트 문서 (README, 기술 가이드) 도서 및 전자책 작성 - 자동 정적 웹사이트 생성 (JBake, Antora) - 기술 발표</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_모범_사례">모범 사례</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>일관된 제목과 자동 목차(:toc:) 를 사용하세요. - 경고를 사용하여 핵심 사항에 주의를 끌세요. - 파일을 구조화하여 유지보수를 쉽게 하세요. - 주석이 달린 코드 블록을 활용하여 예시를 보여주세요.</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_결론">결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>AsciiDoc은 기술 문서나 구조화된 기사를 작성하기 위한 강력하고 접근하기 쉬운 도구입니다. 풍부한 구문과 멀티 포맷 생성이 결합되어, 까다로운 개발자와 작가에게 이상적인 도구가 됩니다. 다음 프로젝트에서 AsciiDoc을 사용해 보고 차이를 경험해 보세요!</p> </div> </div> </div> <div class="sect1"> <h2 id="_더_나아가기">더 나아가기</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>공식 문서 : <a href="https://asciidoc.org" class="bare">https://asciidoc.org</a> - Asciidoctor: <a href="https://asciidoctor.org" class="bare">https://asciidoctor.org</a> - JBake와 AsciiDoc: <a href="https://jbake.org/docs/2.6.4/#asciidoc_support" class="bare">https://jbake.org/docs/2.6.4/#asciidoc_support</a></p> </li> </ul> </div> <div class="paragraph"> <p>경험과 팁을 댓글로 공유해 주세요!</p> </div> </div> </div> https://cheroliv.com/blog/2025/0076_port_forwarding_post.html Wed, 28 May 2025 00:00:00 +0000 blog/2025/0076_port_forwarding_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_문제_nat와_개인_주소">문제: NAT와 개인 주소</a></li> <li><a href="#_단계_1_공용_ip_주소_식별">단계 1 : 공용 IP 주소 식별</a></li> <li><a href="#_단계_2_ubuntu_기기의_로컬_ip_주소를_확인합니다">단계 2: Ubuntu 기기의 로컬 IP 주소를 확인합니다</a></li> <li><a href="#_3단계_박스에서_포트_포워딩_설정하기">3단계: 박스에서 포트 포워딩 설정하기</a> <ul class="sectlevel2"> <li><a href="#_관리자_인터페이스에_접근">관리자 인터페이스에 접근</a></li> <li><a href="#_리다이렉션_구성">리다이렉션 구성</a></li> </ul> </li> <li><a href="#_4단계_ubuntu에서_서비스_구성">4단계 : Ubuntu에서 서비스 구성</a></li> <li><a href="#_5단계_ubuntu_방화벽_구성">5단계: Ubuntu 방화벽 구성</a></li> <li><a href="#_단계_6_테스트_및_검증">단계 6: 테스트 및 검증</a> <ul class="sectlevel2"> <li><a href="#_로컬_네트워크에서_테스트">로컬 네트워크에서 테스트</a></li> <li><a href="#_외부에서_테스트">외부에서 테스트</a></li> </ul> </li> <li><a href="#_모범_사례_및_보안">모범 사례 및 보안</a> <ul class="sectlevel2"> <li><a href="#_기본_보안">기본 보안</a></li> <li><a href="#_연결_모니터링">연결 모니터링</a></li> <li><a href="#_리버스_프록시_사용">리버스 프록시 사용</a></li> </ul> </li> <li><a href="#_포트_포워딩_대안">포트 포워딩 대안</a> <ul class="sectlevel2"> <li><a href="#_클라우드_솔루션">클라우드 솔루션</a></li> <li><a href="#_vps_및_리버스_프록시">VPS 및 리버스 프록시</a></li> </ul> </li> <li><a href="#_문제_해결">문제 해결</a> <ul class="sectlevel2"> <li><a href="#_일반적인_문제">일반적인 문제</a></li> <li><a href="#_네트워크_디버그">네트워크 디버그</a></li> </ul> </li> <li><a href="#_결론">결론</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="ulist"> <div class="title">l 대상 : 중간</div> <ul> <li> <p><strong>전제 조건</strong> : 우분투, 터미널, 기본 네트워크 개념에 대한 기본 지식</p> </li> <li> <p><strong>기술적 개념</strong> : NAT, 포트 포워딩, 방화벽, 역방향 프록시</p> </li> <li> <p><strong>시스템 명령어</strong> : 터미널 사용, 네트워크 구성</p> </li> <li> <p><strong>고급 섹션</strong> : 모니터링, 보안, 클라우드 대안</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_문제_nat와_개인_주소">문제: NAT와 개인 주소</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">문제 : Ubuntu 머신에서 웹 애플리케이션을 개발하고 있고, 이를 가정 네트워크 외부에서 접근 가능하게 만들고 싶으신가요? 그렇다면 올바른 곳에 오셨습니다! 이 글에서는 인터넷 박스의 포트 포워딩을 설정하여 로컬 서비스(예: 포트 8080)를 인터넷에 노출하는 방법을 알아볼게요.</div> <p>기본적으로, 귀하의 인터넷 박스는 NAT(네트워크 주소 변환)를 사용하여 가정 네트워크의 모든 기기 간에 하나의 공용 IP 주소를 공유합니다. 로컬 머신은 인터넷에서 라우팅될 수 없는 사설 IP 주소(192.168.x.x, 10.x.x.x 등)를 사용합니다.</p> </div> <div class="paragraph"> <p>Ubuntu 머신에서 서비스를 실행할 때(예: 포트 8080의 웹 서버), 해당 서비스는 로컬 네트워크에서만 접근할 수 있습니다. 인터넷에서 접근할 수 있도록 하려면 포트 포워딩을 구성해야 합니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_단계_1_공용_ip_주소_식별">단계 1 : 공용 IP 주소 식별</h2> <div class="sectionbody"> <div class="paragraph"> <p>먼저, 인터넷 연결의 공개 IP 주소를 가져옵시다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Plusieurs méthodes au choix curl ifconfig.me curl ipecho.net/plain wget -qO- http://ipecho.net/plain # Ou encore curl -s checkip.amazonaws.com</code></pre> </div> </div> <div class="paragraph"> <p>이 IP 주소는 사용자들이 귀하의 서비스에 접속할 때 사용할 주소입니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_단계_2_ubuntu_기기의_로컬_ip_주소를_확인합니다">단계 2: Ubuntu 기기의 로컬 IP 주소를 확인합니다</h2> <div class="sectionbody"> <div class="paragraph"> <p>귀하의 Ubuntu 머신은 로컬 네트워크에서 사설 IP 주소를 가지고 있습니다. 이를 확인하려면 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Afficher toutes les interfaces réseau ip addr show # Ou plus spécifiquement pour l'interface principale ip route get 1.1.1.1 | awk '{print $7; exit}' # Alternative avec hostname hostname -I | awk '{print $1}'</code></pre> </div> </div> <div class="paragraph"> <p>이 주소를 기록해 두세요 (예시`192.168.1.100`우리는 이것이 구성을 위해 필요할 것입니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_3단계_박스에서_포트_포워딩_설정하기">3단계: 박스에서 포트 포워딩 설정하기</h2> <div class="sectionbody"> <div class="paragraph"> <p>구성은 박스 모델에 따라 다르지만 원리는 동일합니다:</p> </div> <div class="sect2"> <h3 id="_관리자_인터페이스에_접근">관리자 인터페이스에 접근</h3> <div class="paragraph"> <p>브라우저를 열고 라우터의 웹 인터페이스로 이동하세요:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Freebox</strong>:`192.168.1.1` ou <code>mafreebox.freebox.fr</code></p> </li> <li> <p><strong>라이브박스 오렌지</strong>:`192.168.1.1`</p> </li> <li> <p><strong>SFR 박스</strong>:`192.168.1.1`</p> </li> <li> <p><strong>Bbox Bouygues</strong>:`192.168.1.254`</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_리다이렉션_구성">리다이렉션 구성</h3> <div class="paragraph"> <p>포트 포워딩 전용 섹션을 찾으세요(이름은 다를 수 있음):</p> </div> <div class="ulist"> <ul> <li> <p>포트 포워딩</p> </li> <li> <p>NAT/PAT</p> </li> <li> <p>포트 포워딩</p> </li> <li> <p>게임 서버</p> </li> </ul> </div> <div class="paragraph"> <p>이 매개변수로 새로운 규칙을 생성하세요:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 75%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">필드</th> <th class="tableblock halign-left valign-top">가치</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">이름/설명</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ubuntu 웹 서비스" (또는 다른 명시적인 이름)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">외부 포트(또는 공용 포트)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8080</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">내부 IP 주소</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ubuntu 머신의 IP 주소 (예: 192.168.1.100)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">내부 포트 (또는 프라이빗 포트)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8080</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">프로토콜</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">TCP</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">상태</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">활성화된</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_4단계_ubuntu에서_서비스_구성">4단계 : Ubuntu에서 서비스 구성</h2> <div class="sectionbody"> <div class="paragraph"> <p>서비스가 localhost가 아닌 모든 인터페이스에서 수신하도록 확인하세요:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># ✅ Correct : écoute sur toutes les interfaces python3 -m http.server 8080 --bind 0.0.0.0 # ❌ Incorrect : écoute seulement en local python3 -m http.server 8080 --bind 127.0.0.1</code></pre> </div> </div> <div class="paragraph"> <p>서비스가 올바르게 수신 중인지 확인하려면 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Vérifier les ports en écoute sudo netstat -tlnp | grep :8080 # ou avec ss (plus moderne) sudo ss -tlnp | grep :8080</code></pre> </div> </div> <div class="paragraph"> <p>당신은 무언가를 보는 것처럼 보여야 합니다.<code>0.0.0.0:8080`그리고 아니다`127.0.0.1:8080</code>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_5단계_ubuntu_방화벽_구성">5단계: Ubuntu 방화벽 구성</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ubuntu는 기본적으로 UFW(Uncomplicated Firewall)를 사용합니다. 상태를 확인하고 필요하면 포트를 허용하세요 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Vérifier le statut du pare-feu sudo ufw status # Si le pare-feu est actif, autoriser le port 8080 sudo ufw allow 8080/tcp # Ou plus spécifiquement pour un service web sudo ufw allow 'Apache' # si vous utilisez Apache sudo ufw allow 'Nginx Full' # si vous utilisez Nginx</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_단계_6_테스트_및_검증">단계 6: 테스트 및 검증</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_로컬_네트워크에서_테스트">로컬 네트워크에서 테스트</h3> <div class="paragraph"> <p>먼저, 로컬 네트워크의 다른 머신에서 접근을 테스트해 보세요:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Remplacez par l'IP locale de votre machine Ubuntu curl http://192.168.1.100:8080</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_외부에서_테스트">외부에서 테스트</h3> <div class="paragraph"> <p>지금, 공용 IP를 사용하여 인터넷에서 테스트해 보세요 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Remplacez par votre IP publique curl http://VOTRE_IP_PUBLIQUE:8080</code></pre> </div> </div> <div class="paragraph"> <p>또한 온라인 도구를 사용할 수 있습니다. 예를 들어:</p> </div> <div class="ulist"> <ul> <li> <p><a href="https://www.yougetsignal.com/tools/open-ports/" class="bare">https://www.yougetsignal.com/tools/open-ports/</a></p> </li> <li> <p><a href="https://canyouseeme.org/" class="bare">https://canyouseeme.org/</a></p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_모범_사례_및_보안">모범 사례 및 보안</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_기본_보안">기본 보안</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Configurer fail2ban pour protéger contre les attaques par force brute sudo apt update && sudo apt install fail2ban # Limiter l'accès avec UFW (exemple : autoriser seulement certaines IP) sudo ufw allow from 203.0.113.0/24 to any port 8080</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_연결_모니터링">연결 모니터링</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Surveiller les connexions en temps réel sudo netstat -an | grep :8080 # Logs des connexions (selon votre application) sudo tail -f /var/log/nginx/access.log # pour Nginx sudo journalctl -f -u your-service # pour un service systemd</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_리버스_프록시_사용">리버스 프록시 사용</h3> <div class="paragraph"> <p>보안과 유연성을 위해 Nginx와 같은 역방향 프록시 사용을 고려해 보세요:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-nginx hljs" data-lang="nginx">server { listen 80; server_name votre-domaine.com; location / { proxy_pass http://localhost:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_포트_포워딩_대안">포트 포워딩 대안</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_클라우드_솔루션">클라우드 솔루션</h3> <div class="ulist"> <ul> <li> <p><strong>ngrok</strong>임시 보안 터널</p> </li> <li> <p><strong>Cloudflare 터널</strong>무료이고 안전한 솔루션</p> </li> <li> <p><strong>serveo.net</strong>: 간단한 SSH 터널</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Exemple avec ngrok ngrok http 8080 # Exemple avec serveo ssh -R 80:localhost:8080 serveo.net</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_vps_및_리버스_프록시">VPS 및 리버스 프록시</h3> <div class="paragraph"> <p>전문적인 용도로는 VPS를 사용하고, 로컬 인프라를 향하는 리버스 프록시를 VPN을 통해 연결하는 것을 고려하세요.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_문제_해결">문제 해결</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_일반적인_문제">일반적인 문제</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 40%;"> <col style="width: 60%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">문제</th> <th class="tableblock halign-left valign-top">해결책</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">외부에서 접근할 수 없는 서비스</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">포트 포워딩 구성을 확인하고 서비스가 0.0.0.0에서 수신 대기 중인지 확인하세요.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">연결이 거부되었습니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">서비스가 시작되지 않았거나 127.0.0.1에서만 수신 대기 중입니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">연결 타임아웃</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">방화벽 문제(박스 또는 Ubuntu) 또는 포트 포워딩이 잘못 구성됨</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">공개 IP는 정기적으로 변경됩니다</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">동적 DNS(DynDNS, No-IP 등)를 구성하세요.</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_네트워크_디버그">네트워크 디버그</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Tester la connectivité locale telnet localhost 8080 # Tester depuis une autre machine du réseau telnet 192.168.1.100 8080 # Vérifier les routes réseau ip route show # Analyser le trafic réseau sudo tcpdump -i any port 8080</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_결론">결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>인터넷에서 로컬 서비스를 노출하려면 포트 포워딩, 보안, 모니터링을 신중하게 구성해야 합니다. 이 접근 방식은 개발이나 개인 프로젝트에는 완벽하지만, 프로덕션 환경에서는 VPS, CDN, 클라우드 서비스와 같은 더 견고한 대안을 고려해야 합니다.</p> </div> <div class="paragraph"> <p>중요한 것은 항상 보안을 마음속에 두는 것입니다: 강력한 비밀번호를 사용하고, 시스템을 정기적으로 업데이트하며, 노출된 서비스에 대한 접근을 모니터링하세요.</p> </div> <div class="paragraph"> <p>주저하지 마시고 경험과 질문을 댓글에 공유해 주세요!</p> </div> </div> </div> https://cheroliv.com/blog/2025/0099_debugging-mockito-gradle-plugin_post.html Sun, 17 Nov 2024 00:00:00 +0000 blog/2025/0099_debugging-mockito-gradle-plugin_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_서론">서론</a></li> <li><a href="#_컨텍스트_plugin_gradle_bakery">컨텍스트 : Plugin Gradle Bakery</a></li> <li><a href="#_문제_1_잘못된_모의mock_확인">문제 #1 : 잘못된 모의(mock) 확인</a> <ul class="sectlevel2"> <li><a href="#_진단">진단</a></li> <li><a href="#_해결책">해결책</a></li> </ul> </li> <li><a href="#_문제_2_연속된_unfinishedstubbingexception">문제 #2: 연속된 UnfinishedStubbingException</a> <ul class="sectlevel2"> <li><a href="#_진단_2">진단</a></li> <li><a href="#_해결책_2">해결책</a></li> </ul> </li> <li><a href="#_문제_3_구성_파일이_존재하지_않습니다">문제 #3 : 구성 파일이 존재하지 않습니다.</a> <ul class="sectlevel2"> <li><a href="#_진단_3">진단</a></li> <li><a href="#_해결책_3">해결책</a></li> </ul> </li> <li><a href="#_문제_4_afterevaluate_와_nullpointerexception">문제 #4 : afterEvaluate 와 NullPointerException</a> <ul class="sectlevel2"> <li><a href="#_진단_4">진단</a></li> <li><a href="#_해결책_4">해결책</a></li> </ul> </li> <li><a href="#_완전한_솔루션">완전한 솔루션</a></li> <li><a href="#_배운_점">배운 점</a> <ul class="sectlevel2"> <li><a href="#_1_올바른_모의_객체_확인">1. 올바른 모의 객체 확인</a></li> <li><a href="#_2_중첩된_모의_객체_피하기">2. 중첩된 모의 객체 피하기</a></li> <li><a href="#_3_평가_콜백을_모의하기">3. 평가 콜백을 모의하기</a></li> <li><a href="#_4_경로_해결_테스트">4. 경로 해결 테스트</a></li> </ul> </li> <li><a href="#_최종_테스트_아키텍처">최종 테스트 아키텍처</a></li> <li><a href="#_결론">결론</a></li> <li><a href="#_자원">자원</a></li> </ul> </div> <div class="sect1"> <h2 id="_서론">서론</h2> <div class="sectionbody"> <div class="paragraph"> <p>Gradle 플러그인 개발 중<strong>베이커리</strong>내 JBake 블로그에서 겉보기에 간단한 문제를 만났습니다: 오류와 함께 실패하는 단위 테스트가 있었습니다.<code>Wanted but not invoked</code>. 이것은 사소한 버그로 보였지만 Mockito와 Kotlin을 사용한 모킹의 미묘함을 이해하기에 완벽한 사례임이 밝혀졌다.</p> </div> <div class="paragraph"> <p>이 글에서는 체계적인 디버깅 여정을 안내하며, 각 해결책이 새로운 문제를 드러내고 최종 해결에 이르기까지의 과정을 보여줍니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_컨텍스트_plugin_gradle_bakery">컨텍스트 : Plugin Gradle Bakery</h2> <div class="sectionbody"> <div class="paragraph"> <p>Bakery 플러그인은 JBake를 감싸는 래퍼로, 정적 사이트 게시를 용이하게 합니다. 다음은 간소화된 구조 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class BakeryPlugin : Plugin<Project> { override fun apply(project: Project) { val extension = project.extensions.create( "bakery", BakeryExtension::class.java ) project.afterEvaluate { if (!project.layout.projectDirectory.asFile .resolve(extension.configPath.get()).exists()) { println("config file does not exists") } else { // C'EST ICI QUE ÇA SE PASSE project.plugins.apply(JBakePlugin::class.java) val site = FileSystemManager.from(project, extension.configPath.get()) // Configuration de JBake... } } } }</code></pre> </div> </div> <div class="paragraph"> <p>실패하던 테스트는 간단했습니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `plugin applies jbake gradle plugin`() { val project = createMockProject() val plugin = BakeryPlugin() plugin.apply(project) verify(project.plugins).apply(JBakePlugin::class.java) }</code></pre> </div> </div> <div class="paragraph"> <p>오류 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">Wanted but not invoked: pluginContainer.apply(class org.jbake.gradle.JBakePlugin); Actually, there were zero interactions with this mock.</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_문제_1_잘못된_모의mock_확인">문제 #1 : 잘못된 모의(mock) 확인</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_진단">진단</h3> <div class="listingblock"> <div class="content"> <pre>@startuml actor Test participant "project.plugins" as PP participant "모의플러그인컨테이너" as MPC participant "BakeryPlugin" as BP Test -> Test: createMockProject() activate Test Test -> MPC: create mock Test -> PP: doReturn mockPluginContainer Test --> Test: return project deactivate Test Test -> BP: apply(project) activate BP BP -> PP: project.plugins PP --> BP: returns mockPluginContainer BP -> MPC: apply(JBakePlugin::class.java) deactivate BP Test -> PP: verify(project.plugins).apply(...) note right ❌ ÉCHEC ! Mockito vérifie "project.plugins" mais l'interaction a eu lieu sur "모의플러그인컨테이너" end note @enduml</pre> </div> </div> <div class="paragraph"> <p>문제: Mockito는 상호작용을 추적할 수 없습니다.<code>project.plugins`그냥 진짜 모의를 반환하는 getter일 뿐이다`mockPluginContainer</code>. 확인은 모의 객체의 인스턴스에서 직접 수행해야 합니다.</p> </div> </div> <div class="sect2"> <h3 id="_해결책">해결책</h3> <div class="paragraph"> <p>수정`createMockProject()`두 객체를 반환하기 위해 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">private fun createMockProject(): Pair<Project, PluginContainer> { val mockPluginContainer = mock<PluginContainer>() val mockProject = mock<Project> { on { plugins } doReturn mockPluginContainer } return Pair(mockProject, mockPluginContainer) }</code></pre> </div> </div> <div class="paragraph"> <p>그리고 테스트를 조정:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `plugin applies jbake gradle plugin`() { val (project, mockPluginContainer) = createMockProject() val plugin = BakeryPlugin() plugin.apply(project) // ✅ Vérification directe sur le bon mock verify(mockPluginContainer).apply(JBakePlugin::class.java) }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_문제_2_연속된_unfinishedstubbingexception">문제 #2: 연속된 UnfinishedStubbingException</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_진단_2">진단</h3> <div class="paragraph"> <p>첫 번째 수정이 적용된 후, 새로운 오류가 나타났습니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">UnfinishedStubbingException: Unfinished stubbing detected here Hints: 3. you are stubbing the behaviour of another mock inside before 'thenReturn' instruction is completed</code></pre> </div> </div> <div class="paragraph"> <p>문제가 있는 코드에서는 Mockito-Kotlin의 DSL 구문을 사용했습니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val mockProject = mock<Project> { on { extensions } doReturn mockExtensionContainer on { plugins } doReturn mockPluginContainer on { logger } doReturn mock() // ❌ PROBLÈME ICI ! }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre>@startuml participant "Mockito" as M participant "모크 빌더" as MB participant "인라인 모의" as IM M -> MB: mock<Project> { ... } activate MB MB -> MB: on { logger } doReturn MB -> IM: mock() activate IM note right ❌ Création d'un nouveau mock PENDANT le stubbing en cours ! Mockito perd le contexte du stubbing parent end note IM --> MB: nouveau mock deactivate IM MB -x M: UnfinishedStubbingException deactivate MB @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_해결책_2">해결책</h3> <div class="paragraph"> <p>만들다<strong>모두</strong>그리고 이를 구성합니다`whenever()` :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">private fun createMockProject(): Pair<Project, PluginContainer> { // 1️⃣ Créer TOUS les mocks d'abord val mockPluginContainer = mock<PluginContainer>() val mockExtensionContainer = mock<ExtensionContainer>() val mockLogger = mock<org.gradle.api.logging.Logger>() val mockProject = mock<Project>() // 2️⃣ Configurer les mocks séparément avec whenever() whenever(mockProject.plugins).thenReturn(mockPluginContainer) whenever(mockProject.extensions).thenReturn(mockExtensionContainer) whenever(mockProject.logger).thenReturn(mockLogger) return Pair(mockProject, mockPluginContainer) }</code></pre> </div> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>황금 규칙</strong>: 절대 부르지 마`mock()`모의 구성 블록 안에. 항상 먼저 mock을 생성한 다음 구성하세요.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_문제_3_구성_파일이_존재하지_않습니다">문제 #3 : 구성 파일이 존재하지 않습니다.</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_진단_3">진단</h3> <div class="paragraph"> <p>올바른 목(mock) 객체가 있더라도, 플러그인이 구성 파일을 찾지 못해서 테스트는 항상 실패했습니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// Dans BakeryPlugin.kt if (!project.layout.projectDirectory.asFile .resolve(extension.configPath.get()).exists()) { println("config file does not exists") return@afterEvaluate // ❌ Sort avant d'appliquer JBake ! }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre>@startuml participant "베이커리플러그인" as BP participant "프로젝트 레이아웃" as PL participant "확장" as EXT participant "파일 시스템" as FS BP -> PL: layout.projectDirectory.asFile PL --> BP: /some/mock/path BP -> EXT: extension.configPath.get() EXT --> BP: "../../site.yml" BP -> BP: resolve("../../site.yml") BP -> FS: exists() ? FS --> BP: false ❌ BP -> BP: return (skip JBake) note right Le plugin ne trouve pas le fichier et sort avant d'appliquer JBake end note @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_해결책_3">해결책</h3> <div class="paragraph"> <p>경로 해결이 작동하도록 모의(mock)를 구성합니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">private fun createMockProject(): Pair<Project, PluginContainer> { // ... autres mocks ... val configFile = File("../../site.yml").canonicalFile val projectDir = configFile.parentFile // Configuration cohérente des chemins whenever(mockConfigPathProperty.get()).thenReturn("site.yml") whenever(mockProjectDirectory.asFile).thenReturn(projectDir) // Maintenant : projectDir.resolve("site.yml") existe ! ✅ }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre>@startuml !define SUCCESS #90EE90 !define PROBLEM #FFB6C1 rectangle "모의 구성" { card "projectDirectory.asFile" SUCCESS card "반환: /real/path/to/project" SUCCESS card "configPath.get()" SUCCESS card "반환: site.yml" SUCCESS card "resolve()" SUCCESS card "/real/path/to/project/site.yml" SUCCESS card "존재()" SUCCESS card "참 ✅" SUCCESS } @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_문제_4_afterevaluate_와_nullpointerexception">문제 #4 : afterEvaluate 와 NullPointerException</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_진단_4">진단</h3> <div class="paragraph"> <p>플러그인은 블록에서 JBake를 적용합니다.<code>afterEvaluate</code>, 그리고 접근한다`buildDirectory.dir()` :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">project.afterEvaluate { // ... project.tasks.withType(JBakeTask::class.java) .getByName("bake").apply { output = project.layout.buildDirectory .dir(site.bake.destDirPath) // ❌ NPE ici ! .get() .asFile } }</code></pre> </div> </div> <div class="paragraph"> <p>모의`buildDirectory.dir()<code>돌아가고 있었다`null</code>.</p> </div> </div> <div class="sect2"> <h3 id="_해결책_4">해결책</h3> <div class="paragraph"> <p>조롱하다`afterEvaluate`즉시 실행되도록 하고 완전히 설정하다`buildDirectory`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">private fun createMockProject(): Pair<Project, PluginContainer> { // ... autres mocks ... val mockBuildDirectory = mock<DirectoryProperty>() val buildDir = File(projectDir, "build") // Mocker dir() pour retourner un Provider valide whenever(mockBuildDirectory.dir(any<String>())).doAnswer { invocation -> val path = invocation.arguments[0] as String val mockDirProvider = mock<Provider<Directory>>() val mockDir = mock<Directory>() whenever(mockDir.asFile).thenReturn(File(buildDir, path)) whenever(mockDirProvider.get()).thenReturn(mockDir) mockDirProvider } // Mocker afterEvaluate pour exécution immédiate whenever(mockProject.afterEvaluate(any<Action<Project>>())).doAnswer { invocation -> val action = invocation.arguments[0] as Action<Project> action.execute(mockProject) // ✅ Exécution synchrone null } return Pair(mockProject, mockPluginContainer) }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre>@startuml participant "테스트" as T participant "베이커리 플러그인" as BP participant "모의 프로젝트" as MP participant "후평가 액션" as AE T -> BP: apply(project) activate BP BP -> MP: afterEvaluate { ... } activate MP note right Mock configuré pour exécuter immédiatement end note MP -> AE: execute(project) activate AE AE -> MP: layout.buildDirectory.dir("구우다") MP --> AE: Provider<Directory> ✅ AE -> MP: plugins.apply(JBakePlugin) deactivate AE MP --> BP: deactivate MP BP --> T: deactivate BP T -> T: verify(mockPluginContainer).apply(...) note right: ✅ SUCCÈS ! @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_완전한_솔루션">완전한 솔루션</h2> <div class="sectionbody"> <div class="paragraph"> <p>여기에 함수입니다.`createMockProject()`마지막으로, 모든 문제를 해결하는 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">private fun createMockProject(): Pair<Project, PluginContainer> { // 1️⃣ CRÉER tous les mocks (pas de nested mocks !) val mockPluginContainer = mock<PluginContainer>() val mockExtensionContainer = mock<ExtensionContainer>() val mockLogger = mock<org.gradle.api.logging.Logger>() val mockTaskContainer = mock<TaskContainer>() val mockConfigPathProperty = mock<Property<String>>() val mockBakeryExtension = mock<BakeryExtension>() val mockProjectDirectory = mock<Directory>() val mockBuildDirectory = mock<DirectoryProperty>() val mockProjectLayout = mock<ProjectLayout>() val mockProject = mock<Project>() // 2️⃣ CONFIGURER la résolution des chemins val configFile = File("../../site.yml").canonicalFile val projectDir = configFile.parentFile val buildDir = File(projectDir, "build") whenever(mockConfigPathProperty.get()).thenReturn("site.yml") whenever(mockConfigPathProperty.isPresent).thenReturn(true) whenever(mockBakeryExtension.configPath).thenReturn(mockConfigPathProperty) whenever(mockProjectDirectory.asFile).thenReturn(projectDir) // 3️⃣ CONFIGURER buildDirectory avec dir() whenever(mockBuildDirectory.dir(any<String>())).doAnswer { invocation -> val path = invocation.arguments[0] as String val mockDirProvider = mock<Provider<Directory>>() val mockDir = mock<Directory>() whenever(mockDir.asFile).thenReturn(File(buildDir, path)) whenever(mockDirProvider.get()).thenReturn(mockDir) mockDirProvider } // 4️⃣ ASSEMBLER le projet whenever(mockProjectLayout.projectDirectory).thenReturn(mockProjectDirectory) whenever(mockProjectLayout.buildDirectory).thenReturn(mockBuildDirectory) whenever(mockExtensionContainer.create("bakery", BakeryExtension::class.java)) .thenReturn(mockBakeryExtension) whenever(mockExtensionContainer.getByType(BakeryExtension::class.java)) .thenReturn(mockBakeryExtension) whenever(mockProject.extensions).thenReturn(mockExtensionContainer) whenever(mockProject.plugins).thenReturn(mockPluginContainer) whenever(mockProject.tasks).thenReturn(mockTaskContainer) whenever(mockProject.layout).thenReturn(mockProjectLayout) whenever(mockProject.logger).thenReturn(mockLogger) whenever(mockProject.projectDir).thenReturn(projectDir) // 5️⃣ CONFIGURER afterEvaluate pour exécution immédiate whenever(mockProject.afterEvaluate(any<Action<Project>>())).doAnswer { invocation -> val action = invocation.arguments[0] as Action<Project> action.execute(mockProject) null } return Pair(mockProject, mockPluginContainer) }</code></pre> </div> </div> <div class="paragraph"> <p>그리고 최종 테스트가 통과됩니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `plugin applies jbake gradle plugin`() { val (project, mockPluginContainer) = createMockProject() val plugin = BakeryPlugin() plugin.apply(project) verify(mockPluginContainer).apply(JBakePlugin::class.java) // ✅ SUCCÈS ! }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_배운_점">배운 점</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>@startmindmap * Mocking avec Mockito ** ✅ Bonnes pratiques *** Créer tous les mocks d'abord *** Configurer avec whenever() séparément *** Vérifier le mock exact, pas un proxy *** Tester la résolution des chemins ** ❌ Pièges à éviter *** mock() dans un bloc de configuration *** Vérifier project.x au lieu de mockX *** Ignorer les blocs afterEvaluate *** Retourner null pour les Providers @endmindmap</pre> </div> </div> <div class="sect2"> <h3 id="_1_올바른_모의_객체_확인">1. 올바른 모의 객체 확인</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// ❌ FAUX verify(project.plugins).apply(JBakePlugin::class.java) // ✅ CORRECT val (project, mockPluginContainer) = createMockProject() verify(mockPluginContainer).apply(JBakePlugin::class.java)</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_2_중첩된_모의_객체_피하기">2. 중첩된 모의 객체 피하기</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// ❌ FAUX - UnfinishedStubbingException val mockProject = mock<Project> { on { logger } doReturn mock() // Nested mock creation ! } // ✅ CORRECT - Créer séparément val mockLogger = mock<org.gradle.api.logging.Logger>() val mockProject = mock<Project>() whenever(mockProject.logger).thenReturn(mockLogger)</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_3_평가_콜백을_모의하기">3. 평가 콜백을 모의하기</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// ✅ afterEvaluate doit s'exécuter pour les tests whenever(mockProject.afterEvaluate(any())).doAnswer { invocation -> val action = invocation.arguments[0] as Action<Project> action.execute(mockProject) null }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_4_경로_해결_테스트">4. 경로 해결 테스트</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// Toujours vérifier que les chemins se résolvent correctement val extension = project.extensions.getByType(BakeryExtension::class.java) val configPath = extension.configPath.get() val projectDir = project.layout.projectDirectory.asFile val resolvedConfig = projectDir.resolve(configPath) println("Resolved config: ${resolvedConfig.absolutePath}") println("Exists: ${resolvedConfig.exists()}")</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_최종_테스트_아키텍처">최종 테스트 아키텍처</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>@startuml package "테스트 레이어" { [Test Class] --> [createMockProject()] } package "모의 창조" { [createMockProject()] --> [Create All Mocks] [Create All Mocks] --> [Configure Paths] [Configure Paths] --> [Configure Callbacks] [Configure Callbacks] --> [Assemble Project] } package "모의 객체" { [Assemble Project] --> [Project Mock] [Assemble Project] --> [PluginContainer Mock] [Assemble Project] --> [Extension Mocks] [Assemble Project] --> [Layout Mocks] } package "플러그인 테스트 중" { [Test Class] --> [BakeryPlugin] [BakeryPlugin] --> [Project Mock] [BakeryPlugin] --> [PluginContainer Mock] } package "검증" { [Test Class] --> [verify(mockPluginContainer)] } @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_결론">결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>테스트 문제처럼 보였던 것이 실제로 훌륭한 사례 연구가 된 것은 :</p> </div> <div class="ulist"> <ul> <li> <p>Mockito와 Kotlin의 세부 사항</p> </li> <li> <p>올바른 객체를 모의하는 것의 중요성</p> </li> <li> <p>테스트에서의 비동기 콜백 관리</p> </li> <li> <p>Gradle 플러그인에서의 경로 해결</p> </li> </ul> </div> <div class="paragraph"> <p>체계적인 디버깅으로 문제를 구성하는 각 층을 이해함으로써 견고하고 유지 가능한 솔루션에 도달할 수 있었다.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>당신의 테스트를 위한 조언</strong>Mockito에서 "Wanted but not invoked"을(를) 마주치면 항상 스스로에게 물어보세요: 1. 올바른 mock을 확인하고 있나요? 2. 모든 mock이 구성 블록 외부에서 생성됩니까? 3. 내 콜백이 정말 실행되고 있나요? 4. 내 경로가 올바르게 해결되고 있나요?</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_자원">자원</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://github.com/mockito/mockito-kotlin">Mockito-Kotlin 문서</a></p> </li> <li> <p><a href="https://docs.gradle.org/current/userguide/custom_plugins.html">Gradle 플러그인 개발 가이드</a></p> </li> <li> <p><a href="https://jbake.org/">JBake 정적 사이트 생성기</a></p> </li> </ul> </div> <hr> <div class="paragraph"> <p>테스트에서 유사한 문제를 겪어보셨나요? 댓글에 경험을 공유해주세요!</p> </div> </div> </div> https://cheroliv.com/blog/2024/0075_kotlin_arrow-traverse_right_and_left_post.html Tue, 24 Sep 2024 00:00:00 +0000 blog/2024/0075_kotlin_arrow-traverse_right_and_left_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_소개">소개</a></li> <li><a href="#_either_모나드가_무엇인가요">Either 모나드가 무엇인가요?</a> <ul class="sectlevel2"> <li><a href="#_왜_either를_사용해야_하나요">왜 Either를 사용해야 하나요?</a></li> </ul> </li> <li><a href="#_맥락">맥락</a></li> <li><a href="#_다양한_접근_방식">다양한 접근 방식</a> <ul class="sectlevel2"> <li><a href="#_클래식한_접근_방식과_when">클래식한 접근 방식과 `when</a></li> <li><a href="#_fold를_사용한_더_간결한_접근">fold`를 사용한 더 간결한 접근</a></li> <li><a href="#_변환_map와_mapleft">변환 `map`와 `mapLeft</a></li> <li><a href="#_getorelse를_사용한_에러_처리">getOrElse`를 사용한 에러 처리</a></li> <li><a href="#_측면_동작에_onleft와_onright">측면 동작에 `onLeft`와 `onRight</a></li> <li><a href="#_flatmap을_사용한_연산_체이닝">flatMap`을 사용한 연산 체이닝</a></li> <li><a href="#_bimap을_사용한_양방향_변환">bimap`을 사용한 양방향 변환</a></li> <li><a href="#_swap_로_측면_교환">swap` 로 측면 교환</a></li> <li><a href="#_사용법_tap_그리고_tapleft">사용법 <code>tap</code> 그리고 <code>tapLeft</code> :</a></li> <li><a href="#_사용법_recover">사용법 <code>recover</code> :</a></li> </ul> </li> <li><a href="#_실용적인_사용_사례">실용적인 사용 사례</a></li> <li><a href="#_결론">결론</a></li> <li><a href="#_더_깊이">더 깊이</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p><em>읽는 데 걸리는 시간 :</em> 12~15분.</p> </div> </div> </div> <div class="sect1"> <h2 id="_소개">소개</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title"><em>대상 :</em> 중급에서 고급 수준의 Kotlin 개발자.</div> <p>Kotlin의 함수형 프로그래밍 세계에서 Arrow 라이브러리는 오류와 대체 사례를 처리하는 강력한 도구를 제공합니다. 이러한 도구들 중에서 모나드`Either`두 가지 가능한 상태: 성공(Right) 또는 실패(Left). 하지만 이 두 상태 사이에서 효율적으로 어떻게 탐색할 수 있을까요? 이것이 바로 이 글에서 우리가 탐구할 내용입니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_either_모나드가_무엇인가요">Either 모나드가 무엇인가요?</h2> <div class="sectionbody"> <div class="paragraph"> <p>모나드`Either`Either` 는 두 가지 상호 배타적인 가능성을 나타내는 데이터 구조입니다. Kotlin과 Arrow에서, 이는 작업의 성공 및 실패 사례를 처리하는 데 자주 사용되며, 전통적인 예외에 대한 우아한 대안을 제공합니다.</p> </div> <div class="sect2"> <h3 id="_왜_either를_사용해야_하나요">왜 Either를 사용해야 하나요?</h3> <div class="olist arabic"> <ol class="arabic"> <li> <p>명시적 오류 처리 : 개발자에게 실패 사례를 고려하도록 강요합니다.</p> </li> <li> <p>함수형 구성: 실패할 수 있는 작업의 체이닝을 용이하게 합니다.</p> </li> <li> <p>타입 안전성 : 오류가 타입 지정되어 있어 더 정확하게 처리하는 데 도움이 됩니다.</p> </li> <li> <p>예외 없이: 부작용과 실행 흐름의 예기치 않은 중단을 피하라.</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_맥락">맥락</h2> <div class="sectionbody"> <div class="paragraph"> <p>당신이 REST API를 개발하고 있다고 상상해 보세요https://spring.io/projects/spring-boot/[Spring Boot,windows=읽기-나중] et <a href="https://kotlinlang.org/">Kotlin</a>, 라이브러리를 사용하여https://arrow-kt.io/[화살,창문=읽기-나중]. 당신은 하나의 기능이 있습니다.<code>findOneUserByEmail`반환하는`Either<Throwable, User></code>. 이 결과를 우아하고 기능적으로 어떻게 처리할 수 있나요?</p> </div> <div class="paragraph"> <p>우리는 User 클래스가 있습니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@file:Suppress( "RemoveRedundantQualifierName", "MemberVisibilityCanBePrivate", "SqlNoDataSourceInspection" ) package webapp.users import arrow.core.Either import arrow.core.left import arrow.core.right import com.fasterxml.jackson.annotation.JsonIgnore import com.fasterxml.jackson.databind.ObjectMapper import jakarta.validation.constraints.NotNull import jakarta.validation.constraints.Pattern import jakarta.validation.constraints.Size import org.springframework.beans.factory.getBean import org.springframework.context.ApplicationContext import org.springframework.data.r2dbc.core.R2dbcEntityTemplate import org.springframework.r2dbc.core.DatabaseClient import org.springframework.r2dbc.core.awaitOne import org.springframework.r2dbc.core.awaitRowsUpdated import webapp.core.property.ANONYMOUS_USER import webapp.core.property.EMPTY_STRING import webapp.core.utils.AppUtils.cleanField import webapp.users.EntityModel.Companion.ID_MEMBER import webapp.users.User.UserDao.Attributes.EMAIL_ATTR import webapp.users.User.UserDao.Attributes.ID_ATTR import webapp.users.User.UserDao.Attributes.LANG_KEY_ATTR import webapp.users.User.UserDao.Attributes.LOGIN_ATTR import webapp.users.User.UserDao.Attributes.PASSWORD_ATTR import webapp.users.User.UserDao.Attributes.VERSION_ATTR import webapp.users.User.UserDao.Constraints.LOGIN_REGEX import webapp.users.User.UserDao.Fields.EMAIL_FIELD import webapp.users.User.UserDao.Fields.ID_FIELD import webapp.users.User.UserDao.Fields.LANG_KEY_FIELD import webapp.users.User.UserDao.Fields.LOGIN_FIELD import webapp.users.User.UserDao.Fields.PASSWORD_FIELD import webapp.users.User.UserDao.Fields.VERSION_FIELD import webapp.users.User.UserDao.Relations.INSERT import webapp.users.security.Role import webapp.users.security.Role.RoleDao import webapp.users.security.UserRole.UserRoleDao import java.util.* import jakarta.validation.constraints.Email as EmailConstraint data class User( override val id: UUID? = null, @field:NotNull @field:Pattern(regexp = LOGIN_REGEX) @field:Size(min = 1, max = 50) val login: String, @JsonIgnore @field:NotNull @field:Size(min = 60, max = 60) val password: String = EMPTY_STRING, @field:EmailConstraint @field:Size(min = 5, max = 254) val email: String = EMPTY_STRING, @JsonIgnore val roles: MutableSet<Role> = mutableSetOf(Role(ANONYMOUS_USER)), @field:Size(min = 2, max = 10) val langKey: String = EMPTY_STRING, @JsonIgnore val version: Long = -1, ) : EntityModel<UUID>() { companion object { @JvmStatic fun main(args: Array<String>) = println(UserDao.Relations.sqlScript) } object UserDao { object Constraints { // Regex for acceptable logins const val LOGIN_REGEX = "^(?>[a-zA-Z0-9!$&*+=?^_`{|}~.-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*)|(?>[_.@A-Za-z0-9-]+)$" const val PASSWORD_MIN: Int = 4 const val PASSWORD_MAX: Int = 16 const val IMAGE_URL_DEFAULT = "https://placehold.it/50x50" const val PHONE_REGEX = "^(\\+|00)?[1-9]\\d{0,49}\$" } object Members { const val PASSWORD_MEMBER = "password" const val ROLES_MEMBER = "roles" } object Fields { const val ID_FIELD = "`id`" const val LOGIN_FIELD = "`login`" const val PASSWORD_FIELD = "`password`" const val EMAIL_FIELD = "`email`" const val LANG_KEY_FIELD = "`lang_key`" const val VERSION_FIELD = "`version`" } object Attributes { val ID_ATTR = ID_FIELD.cleanField() val LOGIN_ATTR = LOGIN_FIELD.cleanField() val PASSWORD_ATTR = PASSWORD_FIELD.cleanField() val EMAIL_ATTR = EMAIL_FIELD.cleanField() const val LANG_KEY_ATTR = "langKey" val VERSION_ATTR = VERSION_FIELD.cleanField() } object Relations { const val TABLE_NAME = "`user`" const val SQL_SCRIPT = """ CREATE TABLE IF NOT EXISTS $TABLE_NAME ( $ID_FIELD UUID default random_uuid() PRIMARY KEY, $LOGIN_FIELD VARCHAR, $PASSWORD_FIELD VARCHAR, $EMAIL_FIELD VARCHAR, $LANG_KEY_FIELD VARCHAR, $VERSION_FIELD bigint ); CREATE UNIQUE INDEX IF NOT EXISTS `uniq_idx_user_login` ON $TABLE_NAME ($LOGIN_FIELD); CREATE UNIQUE INDEX IF NOT EXISTS `uniq_idx_user_email` ON $TABLE_NAME ($EMAIL_FIELD); """ @Suppress("SqlDialectInspection") const val INSERT = """ insert into $TABLE_NAME ( $LOGIN_FIELD, $EMAIL_FIELD, $PASSWORD_FIELD, $LANG_KEY_FIELD, $VERSION_FIELD ) values ( :login, :email, :password, :langKey, :version)""" @JvmStatic val sqlScript: String get() = setOf( UserDao.Relations.SQL_SCRIPT, RoleDao.Relations.SQL_SCRIPT, UserRoleDao.Relations.SQL_SCRIPT ).joinToString("") .trimMargin() } object Dao { val Pair<User, ApplicationContext>.toJson: String get() = second.getBean<ObjectMapper>().writeValueAsString(first) suspend fun Pair<User, ApplicationContext>.save(): Either<Throwable, Long> = try { second.getBean<R2dbcEntityTemplate>() .databaseClient .sql(INSERT) .bind(LOGIN_ATTR, first.login) .bind(EMAIL_ATTR, first.email) .bind(PASSWORD_ATTR, first.password) .bind(LANG_KEY_ATTR, first.langKey) .bind(VERSION_ATTR, first.version) .fetch() .awaitRowsUpdated() .right() } catch (e: Throwable) { e.left() } suspend fun ApplicationContext.findOneUserByEmail( email: String ): Either<Throwable, User> = try { getBean<DatabaseClient>() .sql("SELECT * FROM `user` WHERE LOWER(email) = LOWER(:email)") .bind("email", email) .fetch() .awaitOne() .let { row -> User( id = row[ID_ATTR] as UUID?, login = row[LOGIN_ATTR] as String, password = row[PASSWORD_ATTR] as String, email = row[EMAIL_ATTR] as String, langKey = row[LANG_KEY_ATTR] as String, version = row[VERSION_ATTR] as Long ) }.right() } catch (e: Throwable) { e.left() } } } /** Account REST API URIs */ object UserRestApis { const val API_AUTHORITY = "/api/authorities" const val API_USERS = "/api/users" const val API_SIGNUP = "/signup" const val API_SIGNUP_PATH = "$API_USERS$API_SIGNUP" const val API_ACTIVATE = "/activate" const val API_ACTIVATE_PATH = "$API_USERS$API_ACTIVATE?key=" const val API_ACTIVATE_PARAM = "{activationKey}" const val API_ACTIVATE_KEY = "key" const val API_RESET_INIT = "/reset-password/init" const val API_RESET_FINISH = "/reset-password/finish" const val API_CHANGE = "/change-password" const val API_CHANGE_PATH = "$API_USERS$API_CHANGE" } } // Abstract entity model with Generic ID, which can be of any type abstract class EntityModel<T>( open val id: T? = null ) { companion object { const val ID_MEMBER = "id" } } // Generic extension function that allows the ID to be applied to any EntityModel type inline fun <reified T : EntityModel<ID>, ID> T.withId(id: ID): T { // Use reflection to create a copy with the passed ID return this::class.constructors.first { it.parameters.any { param -> param.name == ID_MEMBER } } .call(id, *this::class.constructors.first().parameters.drop(1).map { param -> this::class.members.first { member -> member.name == param.name }.call(this) }.toTypedArray()) }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_다양한_접근_방식">다양한 접근 방식</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_클래식한_접근_방식과_when">클래식한 접근 방식과 `when</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val user: User by lazy { userFactory(USER) } val result: Either<Throwable, User> = context.findOneUserByEmail(user.email) when (result) { is Either.Left -> { val error = result.value println("Erreur : ${error.message}") } is Either.Right -> { val user = result.value println("Utilisateur trouvé : ${user.login}") } }</code></pre> </div> </div> <div class="paragraph"> <p>이 방법은 간단하고 가독성이 좋지만, Arrow의 함수형 기능을 충분히 활용하지 못합니다.</p> </div> </div> <div class="sect2"> <h3 id="_fold를_사용한_더_간결한_접근">fold`를 사용한 더 간결한 접근</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">result.fold( { error -> println("Erreur : ${error.message}") }, { user -> println("Utilisateur trouvé : ${user.login}") } )</code></pre> </div> </div> <div class="paragraph"> <p>`fold`두 경우(Left와 Right)에 대해 간결하고 우아하게 동작을 정의할 수 있습니다.</p> </div> </div> <div class="sect2"> <h3 id="_변환_map와_mapleft">변환 `map`와 `mapLeft</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val processedResult = result .map { user -> "Utilisateur trouvé : ${user.login}" } .mapLeft { error -> "Erreur : ${error.message}" } println(processedResult.merge())</code></pre> </div> </div> <div class="paragraph"> <p>이 접근 방식은 Either에 포함된 값을 변환하면서 구조를 보존할 수 있게 하여, 보다 복잡한 처리 체인에 적합합니다.</p> </div> </div> <div class="sect2"> <h3 id="_getorelse를_사용한_에러_처리">getOrElse`를 사용한 에러 처리</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val user = result.getOrElse { error -> println("Erreur : ${error.message}") User(login = "default", email = "default@example.com") // utilisateur par défaut } println("Login : ${user.login}")</code></pre> </div> </div> <div class="paragraph"> <p>`getOrElse`기본 값을 제공함으로써 우아한 오류 관리를 제공합니다.</p> </div> </div> <div class="sect2"> <h3 id="_측면_동작에_onleft와_onright">측면 동작에 `onLeft`와 `onRight</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">result.onLeft { error -> println("Erreur : ${error.message}") } .onRight { user -> println("Utilisateur trouvé : ${user.login}") }</code></pre> </div> </div> <div class="paragraph"> <p>이러한 메서드는 Either를 수정하지 않고 각 쪽에서 작업을 수행할 수 있게 해 주며, 로깅이나 가벼운 부작용에 적합합니다.</p> </div> </div> <div class="sect2"> <h3 id="_flatmap을_사용한_연산_체이닝">flatMap`을 사용한 연산 체이닝</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">fun findUser(email: String): Either<Throwable, User> = // ... implémentation fun getUserPermissions(user: User): Either<Throwable, List<String>> = // ... implémentation val userPermissions = findUser("user@example.com") .flatMap { user -> getUserPermissions(user) }</code></pre> </div> </div> <div class="paragraph"> <p><code>flatMap`연쇄적으로 실행되는 작업을 이어가기에 유용합니다. 즉, 작업을 실행하면 자신이 다시 작업을 반환합니다.`Either</code>, 그렇게 하여 …​을 피함`Either`중첩된.</p> </div> </div> <div class="sect2"> <h3 id="_bimap을_사용한_양방향_변환">bimap`을 사용한 양방향 변환</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val result: Either<Throwable, User> = // ... obtention du résultat val processedResult = result.bimap( { error -> "Erreur: ${error.message}" }, { user -> "Utilisateur: ${user.login}" } )</code></pre> </div> </div> <div class="paragraph"> <p>`bimap`양쪽을 동시에 한 번의 작업으로 변환할 수 있습니다.</p> </div> </div> <div class="sect2"> <h3 id="_swap_로_측면_교환">swap` 로 측면 교환</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val result: Either<Throwable, User> = // ... obtention du résultat val swapped = result.swap()</code></pre> </div> </div> <div class="paragraph"> <p><code>swap`는 당신이 어떤 것의 옆을 뒤집고 싶을 때 유용합니다`Either</code>, 예를 들어 한 함수의 인터페이스를 다른 함수에 맞게 조정하기 위해.</p> </div> </div> <div class="sect2"> <h3 id="_사용법_tap_그리고_tapleft">사용법 <code>tap</code> 그리고 <code>tapLeft</code> :</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">result.tap { user -> println("Utilisateur trouvé : ${user.login}") } .tapLeft { error -> println("Erreur : ${error.message}") }</code></pre> </div> </div> <div class="paragraph"> <p>비슷한`onLeft` et <code>onRight</code>, 하지만 이러한 메서드는 원래의 Either를 반환하며, 이는 연산 체이닝에 유용합니다.</p> </div> </div> <div class="sect2"> <h3 id="_사용법_recover">사용법 <code>recover</code> :</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val recoveredUser = result.recover { error -> println("Erreur récupérée : ${error.message}") User(login = "recovered", email = "recovered@example.com") } println("Login : ${recoveredUser.login}")</code></pre> </div> </div> <div class="paragraph"> <p>이 메서드는 대체 값을 제공하여 Either.Left를 Either.Right로 변환할 수 있습니다.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_실용적인_사용_사례">실용적인 사용 사례</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>사용하세요`fold`간단한 작업에 대해 각 경우에 처리가 필요한 경우. - 선호하세요`map` et <code>mapLeft`데이터 변환을 위해 구조를 바꾸지 않고`Either</code>. - 선택하세요`flatMap`실패할 수 있는 작업을 연쇄할 때 사용하세요`recover`오류 시 기본값을 제공하기 위해. - 선택하세요`onLeft` et <code>onRight</code> (ou <code>tap</code> et <code>tapLeft</code>) 부수적인 효과, 예를 들어 로깅과 같은 것을 위해. - 사용하세요`bimap`양쪽을 하나의 작업으로 변환하기. - 적용하세요`swap`함수의 인터페이스를 다른 함수의 인터페이스에 맞춰야 할 때.</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_결론">결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>이러한 접근 방식 각각은 사용 맥락에 따라 장점이 있습니다. 방법과 같은`fold`, <code>map</code>/<code>mapLeft</code>, et `recover`는 여러 작업을 연결하거나 데이터를 함수형 방식으로 변환할 때 특히 유용합니다.</p> </div> <div class="paragraph"> <p>일원자`Either`dArrow는 Kotlin 애플리케이션에서 성공과 오류 사례를 처리하는 데 뛰어난 유연성을 제공합니다. 이러한 다양한 접근 방식을 숙달하면 더 견고하고 읽기 쉽고 기능적인 코드를 작성할 수 있습니다.</p> </div> <div class="paragraph"> <p>다음 프로젝트에서 이러한 기법을 탐색하여 Kotlin과 Arrow로 함수형 프로그래밍의 장점을 최대한 활용해 보세요 !</p> </div> </div> </div> <div class="sect1"> <h2 id="_더_깊이">더 깊이</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Arrow 공식 문서 :https://arrow-kt.io/docs/apidocs/arrow-core/arrow.core/-either/[Arrow Either] - Kotlin 코루틴과 Arrow :https://arrow-kt.io/docs/fx/[화살 이펙트 코루틴]</p> </li> </ul> </div> <div class="paragraph"> <p>경험과 선호하는 기술을 공유하는 것을 잊지 마세요`Either`아래 댓글에서!</p> </div> </div> </div> https://cheroliv.com/blog/2024/0074_seach_file_linux_post.html Mon, 23 Sep 2024 00:00:00 +0000 blog/2024/0074_seach_file_linux_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_소개">소개</a></li> <li><a href="#_명령어_find_사용">명령어 <code>find</code> 사용</a> <ul class="sectlevel2"> <li><a href="#_find에_대한_추가_옵션">find`에 대한 추가 옵션</a></li> </ul> </li> <li><a href="#_명령어_사용_locate">명령어 사용 `locate</a></li> <li><a href="#_grep_명령어를_사용하여_파일_내에서_텍스트를_검색">grep` 명령어를 사용하여 파일 내에서 텍스트를 검색</a></li> <li><a href="#_결론">결론</a></li> </ul> </div> <div class="sect1"> <h2 id="_소개">소개</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">문제 제기 : 터미널을 통해 리눅스 운영 체제에서 파일을 검색합니다.</div> <p>이 글에서는 Zsh 터미널을 사용하여 Ubuntu에서 파일을 검색하는 방법을 탐구해 보겠습니다. Zsh(Z shell)는 유연성과 고급 기능으로 인해 널리 사용되는 강력한 명령어 해석기입니다.</p> </div> <div class="paragraph"> <p>Ubuntu은(는) 인기 있는 Linux 배포판으로, 파일을 검색하는 여러 명령줄 도구를 제공합니다. 우리는 다음과 같은 명령어를 사용하는 방법을 살펴볼 것입니다.<code>find</code>, <code>locate</code> et `grep`터미널에서 파일을 빠르게 효율적으로 찾기 위해</p> </div> </div> </div> <div class="sect1"> <h2 id="_명령어_find_사용">명령어 <code>find</code> 사용</h2> <div class="sectionbody"> <div class="paragraph"> <p>명령어`find`특정 디렉토리와 그 하위 디렉토리에서 파일을 검색할 수 있습니다. 기본 구문은 다음과 같습니다 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">find [chemin] -name [nom_du_fichier]</code></pre> </div> </div> <div class="paragraph"> <p>다음은 이름을 가진 파일을 찾는 실용적인 예시입니다.<code>example.txt`디렉토리 안에</code>/home`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">find /home -name "example.txt"</code></pre> </div> </div> <div class="paragraph"> <p>이 명령은 모든 하위 디렉터리를 탐색할 것입니다.`/home`그리고 파일이 발견되면 파일 전체 경로를 표시합니다.</p> </div> <div class="paragraph"> <p><strong>명령어 온라인 매뉴얼`find` : <a href="https://man.archlinux.org/man/find.1.fr/">남자 찾다</a></strong></p> </div> <div class="sect2"> <h3 id="_find에_대한_추가_옵션">find`에 대한 추가 옵션</h3> <div class="paragraph"> <p>명령어`find`는 매우 강력하고 많은 옵션을 제공합니다. 다음은 몇 가지 유용한 예시 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>파일 유형별로 검색</strong>파일만 검색하려면 사용하세요`-type f`, 그리고 디렉터리를 검색하려면, 사용하세요`-type d`. - <strong>크기별로 검색</strong>파일 크기에 따라 파일을 필터링할 수도 있습니다. 옵션을 사용해서`-size`. Par exemple, pour rechercher des fichiers de plus de 100 Mo, utilisez :</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">find /home -size +100M</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_명령어_사용_locate">명령어 사용 `locate</h2> <div class="sectionbody"> <div class="paragraph"> <p>명령`locate`더 빠른`find`이유는 사전 인덱싱된 시스템에 존재하는 파일들의 데이터베이스를 사용하기 때문입니다. 먼저 다음 명령으로 이 데이터베이스를 업데이트해야 합니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo updatedb</code></pre> </div> </div> <div class="paragraph"> <p>다음에 다음과 같이 파일을 검색할 수 있습니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">locate example.txt</code></pre> </div> </div> <div class="paragraph"> <p>사용하고 있어요https://fr.wikipedia.org/wiki/Z_Shell[zsh]와/과https://github.com/ohmyzsh/ohmyzsh/wiki[oh-my-zsh], 명령이라는 것이 드러났습니다`locate`접근할 수 없습니다`zsh`하지만 가능한`bash`, 이를 보완하기 위해, 논거`-c`명령의`bash`명령을 실행할 수 있게 함`bash`다른 종류의 터미널에서.</p> </div> <div class="paragraph"> <p>여기서 저는 패턴으로 끝나는 파일을 찾고 있습니다.`001.pdf`사용자 디렉터리 안에</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">bash -c "locate ~/*001.pdf"</code></pre> </div> </div> <div class="paragraph"> <p><strong>명령의 온라인 매뉴얼`locate`:https://man.archlinux.org/man/locate.1.fr/[man locate, windows=읽기-나중]</strong></p> </div> </div> </div> <div class="sect1"> <h2 id="_grep_명령어를_사용하여_파일_내에서_텍스트를_검색">grep` 명령어를 사용하여 파일 내에서 텍스트를 검색</h2> <div class="sectionbody"> <div class="paragraph"> <p>파일 안에서 특정 텍스트를 검색하려면 다음을 사용할 수 있습니다.<code>grep</code>. 예를 들어, 모든 파일에서 "Ubuntu" 단어의 발생을 검색하려면`.txt`현재 디렉터리에서 사용 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">grep "Ubuntu" *.txt</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_결론">결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>우분투에서 Zsh 터미널을 통해 파일을 찾는 작업은 여러 강력한 도구를 사용하여 수행할 수 있습니다.`find`유연하며 다양한 옵션을 제공하지만`locate`를 통해 사전 구축된 데이터베이스를 이용한 빠른 검색이 가능합니다. 마지막으로,`grep`파일 내부에서 텍스트 발생을 찾을 수 있습니다.</p> </div> <div class="paragraph"> <p>이 명령어들은 파일을 더 효율적으로 검색하고 여러분의 필요에 맞게 조정할 수 있는 포괄적인 도구 세트를 제공하며, 각 명령어는 해당 명령을 통해 볼 수 있는 매뉴얼을 가지고 있습니다.<code>man</code></p> </div> </div> </div> https://cheroliv.com/blog/2021/0030_memo_linux_post.html Mon, 23 Sep 2024 00:00:00 +0000 blog/2021/0030_memo_linux_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_키보드">키보드 :</a> <ul class="sectlevel2"> <li><a href="#_키_ctrl"><em>키 <Ctrl></em></a></li> </ul> </li> <li><a href="#_허가승인">허가(승인)</a></li> <li><a href="#_파일_검색">파일 검색</a></li> </ul> </div> <div class="sect1"> <h2 id="_키보드">키보드 :</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_키_ctrl"><em>키 <Ctrl></em></h3> <table class="tableblock frame-all grid-all stretch"> </table> <div class="paragraph"> <p><a href="https://korben.info/les-raccourcis-clavier-pour-bash-terminal-linux-et-macos.html">링크</a><br> <a href="https://blogmotion.fr/systeme/astuces-bash-linux-16175">다른 링크</a></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_허가승인">허가(승인)</h2> <div class="sectionbody"> <div class="paragraph"> <p>CHMOD은 파일의 권한을 변경하는 데 사용됩니다.</p> </div> <div class="paragraph"> <p>권한 명령</p> </div> <div class="paragraph"> <p>U G W rwx rwx rwx chmod 777 filename rwx rwx r-x chmod 775 파일명 rwx r-x r-x chmod 755 파일명 rw- rw- r-- chmod 664 filename rw- r-- r-- chmod 644 파일 이름</p> </div> <div class="paragraph"> <p>U = 사용자 G = 그룹 W = 세계</p> </div> <div class="paragraph"> <p>r = Readable w = 쓰기 가능 x = 실행 파일 - = 권한 없음</p> </div> <div class="paragraph"> <p>권한을 보는 다른 방법:</p> </div> <div class="paragraph"> <p>400 소유자가 읽음 040 그룹이 읽음 004 누구든지 읽을 수 있음 (다른) 200 소유자가 작성 020 그룹별로 쓰기 누구나 쓸 수 있다 100 소유자에 의해 실행 010 그룹별로 실행 001 누구에 의해 실행</p> </div> <div class="paragraph"> <p>조합을 얻으려면 단순히 그들을 더하기만 하면 됩니다.<br> 소유자가 읽고, 쓰고, 실행할 수 있도록,<br> 읽은, 실행된, 그룹에 의해 실행된 및 누구에 의해 실행된,<br> 당신은 400+200+100+040+010+001을 더하면 751이 됩니다.<br></p> </div> </div> </div> <div class="sect1"> <h2 id="_파일_검색"><a href="/blog/2024/0074_seach_file_linux_post.html">파일 검색</a></h2> <div class="sectionbody"> </div> </div> https://cheroliv.com/blog/2024/0072_Exposer_un_port_linux_subsystem_post.adoc.html Thu, 1 Feb 2024 00:00:00 +0000 blog/2024/0072_Exposer_un_port_linux_subsystem_post.adoc.html https://cheroliv.com/blog/2024/0070_installer_pandoc_post.html Tue, 30 Jan 2024 00:00:00 +0000 blog/2024/0070_installer_pandoc_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title"><em>읽는 데 걸리는 시간 : 3분</em> Pandoc는 범용 문서 변환기입니다.</div> <p>Pandoc는 서로 다른 형식 간에 문서를 변환하는 데 사용할 수 있는 오픈 소스 텍스트 처리 소프트웨어입니다. Pandoc을 설치하는 방법에는 여러 가지가 있습니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_다운로드_페이지에서_설치하기"><strong>다운로드 페이지에서 설치하기</strong></h2> <div class="sectionbody"> <div class="paragraph"> <p>Pandoc을 다운로드 페이지에서 설치하려면 다음과 같이 진행하세요:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Pandoc 다운로드 페이지로 이동하세요 :https://pandoc.org/installing.html/[<a href="https://pandoc.org/installing.html" class="bare">https://pandoc.org/installing.html</a>]</p> </li> <li> <p>운영 체제용 패키지 설치 프로그램을 다운로드하세요.</p> </li> <li> <p>설치 프로그램을 실행하여 Pandoc를 설치하세요.</p> </li> </ol> </div> <div class="paragraph"> <p><strong>ZIP 파일에서 설치</strong></p> </div> <div class="paragraph"> <p>Pandoc를 zip 파일에서 설치하려면 다음 단계를 따르세요:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Pandoc 바이너리와 설명서가 포함된 zip 파일을 다운로드하세요.</p> </li> <li> <p>ZIP 파일을 압축 해제하세요.</p> </li> <li> <p>바이너리 파일을 원하는 디렉터리로 이동하세요.</p> </li> </ol> </div> <div class="paragraph"> <p><strong>Chocolatey를 사용한 설치</strong></p> </div> <div class="paragraph"> <p>Chocolatey를 사용하여 Pandoc을 설치하려면 다음 단계를 따르세요:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>명령 프롬프트를 여십시오.</p> </li> <li> <p>다음 명령을 실행하세요:</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-powershell hljs" data-lang="powershell">choco install pandoc</code></pre> </div> </div> <div class="paragraph"> <p><strong>winget을 사용한 설치</strong></p> </div> <div class="paragraph"> <p>winget을 사용하여 Pandoc을 설치하려면 다음 단계를 따르세요 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>명령 프롬프트를 여세요.</p> </li> <li> <p>다음 명령을 실행하세요:</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-powershell hljs" data-lang="powershell">winget install --source winget --exact --id JohnMacFarlane.Pandoc</code></pre> </div> </div> <div class="paragraph"> <p><strong>권고</strong></p> </div> <div class="paragraph"> <p>기본적으로 Pandoc은 LaTeX를 사용하여 PDF를 만듭니다. LaTeX를 MiKTeX를 통해 설치하는 것이 권장됩니다. 옵션과 함께`--pdf-engine`, 그러나 이 작업에 다른 프로그램을 지정할 수 있습니다.</p> </div> <div class="paragraph"> <p><strong>주의</strong></p> </div> <div class="paragraph"> <p>여러 설치 방법을 사용하면 Pandoc이 두 개의 별도 설치로 이어질 수 있습니다. 대체 설치 방법으로 전환하기 전에 Pandoc을 올바르게 제거하는 것이 좋습니다.</p> </div> <div class="paragraph"> <p><strong>WSL을 통한 리눅스 설치</strong></p> </div> <div class="paragraph"> <p>패키지 관리자에 있는 pandoc 버전이 오래되지 않았는지 확인하세요. Pandoc은 Debian, Ubuntu, Slackware, Arch, Fedora, NixOS, openSUSE, gentoo 및 Void 저장소에 있습니다.</p> </div> <div class="paragraph"> <p>최신 버전을 얻으려면, amd64 아키텍처용 바이너리 패키지를 다운로드 페이지에서 제공합니다.</p> </div> <div class="paragraph"> <p>실행 파일은 정적으로 연결되어 있고 동적 의존성도 없으며 외부 데이터 파일에 대한 의존성도 없습니다. 주의: 정적 링크 때문에 이 패키지의 pandoc 바이너리는 C로 작성된 외부 Lua 모듈을 필요로 하는 Lua 필터를 사용할 수 없습니다.</p> </div> <div class="paragraph"> <p>tarball과 deb 설치 프로그램이 제공됩니다. deb를 설치하려면 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo dpkg -i $DEB</code></pre> </div> </div> <div class="paragraph"> <p>작성 시점의 예시:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">wget https://github.com/jgm/pandoc/releases/download/3.1.11.1/pandoc-3.1.11.1-1-amd64.deb</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo dpkg -i pandoc-3.1.11.1-1-amd64.deb</code></pre> </div> </div> <div class="paragraph"> <p>où `$DEB`다운로드된 deb 파일의 경로입니다. 이 실행 파일을 설치합니다.`pandoc`그리고 매뉴얼 페이지.</p> </div> <div class="paragraph"> <p>RPM 기반 배포판을 사용 중이라면, 우리 다운로드 페이지의 deb 파일을 alien을 통해 설치할 수 있을 수도 있습니다.</p> </div> <div class="paragraph"> <p>어떤 배포판이든 tarball에서 설치할 수 있습니다`$DEST`(예를 들어,<code>/usr/local/</code> ou <code>$HOME/.local</code>) 하기 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">tar xvzf $TGZ --strip-components 1 -C $DEST</code></pre> </div> </div> <div class="paragraph"> <p>où `$TGZ`다운로드된 압축 tarball의 경로입니다. Pandoc 2.0 이전 버전은 tarball을 제공하지 않으므로 대신 다음을 시도해 보세요 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">ar p $DEB data.tar.gz | tar xvz --strip-components 2 -C $DEST</code></pre> </div> </div> <div class="paragraph"> <p>또한 소스에서 설치할 수도 있으며, 아래 지침을 사용하여 설치할 수도 있습니다`Compilation à partir de la source`. 대부분의 배포판이 Haskell 플랫폼을 저장소에 포함하고 있다는 점에 유의하세요. 예를 들어, Debian/Ubuntu에서는 다음으로 설치할 수 있습니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">apt-get install haskell-platform</code></pre> </div> </div> <div class="paragraph"> <p>기본적으로 Pandoc은 LaTeX를 사용하여 PDF를 생성합니다. 우리는 패키지 관리자를 통해 TeX Live 설치를 권장합니다. (Debian/Ubuntu에서,<code>apt-get install texlive</code>). 옵션과 함께`--pdf-engine`, 그러나 다른 프로그램을 지정할 수 있습니다.</p> </div> </div> </div> https://cheroliv.com/blog/2023/0069_triple_python_js_ts_post.html Mon, 25 Dec 2023 00:00:00 +0000 blog/2023/0069_triple_python_js_ts_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title"><em>읽는 시간: 2분</em> 함수형 프로그래밍을 사용해 JavaScript, TypeScript, Python에서 kotlin.Triple 클래스의 완전한 구현을 만드세요.</div> <p><strong>Note :</strong>유형`Maybe`, <code>Either</code>, `Result`자바스크립트 또는 타입스크립트의 기본 언어에 포함되지 않으므로 우리가 직접 구현해야 합니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_자바스크립트">자바스크립트</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">//javascript // Maybe type const Maybe = (value) => ({ map: (fn) => (value !== null && value !== undefined ? Maybe(fn(value)) : Maybe(null)), flatMap: (fn) => (value !== null && value !== undefined ? fn(value) : Maybe(null)), getOrElse: (defaultValue) => (value !== null && value !== undefined ? value : defaultValue), }); // Either type const Either = { Left: (value) => ({ map: (fn) => Either.Left(value), flatMap: (fn) => Either.Left(value), getOrElse: (defaultValue) => defaultValue, isLeft: true, isRight: false, }), Right: (value) => ({ map: (fn) => Either.Right(fn(value)), flatMap: (fn) => fn(value), getOrElse: (defaultValue) => value, isLeft: false, isRight: true, }), }; // Triple class class Triple { constructor(a, b, c) { this.a = a; this.b = b; this.c = c; } map(fn) { return new Triple(fn(this.a), fn(this.b), fn(this.c)); } static of(a, b, c) { return new Triple(a, b, c); } // Example method using Maybe and Either divideBy(other) { return Maybe(this.b) .flatMap((numerator) => Maybe(other) .flatMap((denominator) => denominator !== 0 ? Either.Right(numerator / denominator) : Either.Left('Division by zero') ) ) .getOrElse(Either.Left('Invalid input')); } } // Example usage const triple = Triple.of(1, 2, 3); const result = triple.map((x) => x * 2); console.log(result); // Triple { a: 2, b: 4, c: 6 } const divisionResult = triple.divideBy(2); console.log(divisionResult); // Either.Right { value: 1 } const invalidDivisionResult = triple.divideBy(0); console.log(invalidDivisionResult); // Either.Left { value: 'Division by zero' }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_타입스크립트">타입스크립트</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-typescript hljs" data-lang="typescript">//Typescript // Maybe type // noinspection JSAnnotator type Maybe<T> = { map<U>(fn: (value: T) => U): Maybe<U>; flatMap<U>(fn: (value: T) => Maybe<U>): Maybe<U>; getOrElse(defaultValue: T): T; }; const just = <T>(value: T): Maybe<T> => ({ map: <U>(fn: (value: T) => U) => just(fn(value)), flatMap: <U>(fn: (value: T) => Maybe<U>) => fn(value), getOrElse: (_: T) => value, }); const nothing = <T>(): Maybe<T> => ({ map: <U>(_: (value: T) => U) => nothing<U>(), flatMap: <U>(_: (value: T) => Maybe<U>) => nothing<U>(), getOrElse: (defaultValue: T) => defaultValue, }); // Either type type Either<L, R> = { map<U>(fn: (value: R) => U): Either<L, U>; flatMap<U>(fn: (value: R) => Either<L, U>): Either<L, U>; getOrElse(defaultValue: R): R; isLeft: boolean; isRight: boolean; }; const left = <L, R>(value: L): Either<L, R> => ({ map: <U>(_: (value: R) => U) => left<L, U>(value), flatMap: <U>(_: (value: R) => Either<L, U>) => left<L, U>(value), getOrElse: (defaultValue: R) => defaultValue, isLeft: true, isRight: false, }); const right = <L, R>(value: R): Either<L, R> => ({ map: <U>(fn: (value: R) => U) => right<L, U>(fn(value)), flatMap: <U>(fn: (value: R) => Either<L, U>) => fn(value), getOrElse: (_: R) => value, isLeft: false, isRight: true, }); // Triple class class Triple<T> { constructor(public a: T, public b: T, public c: T) {} map<U>(fn: (value: T) => U): Triple<U> { return new Triple<U>(fn(this.a), fn(this.b), fn(this.c)); } static of<T>(a: T, b: T, c: T): Triple<T> { return new Triple<T>(a, b, c); } // Example method using Maybe and Either divideBy(other: T): Either<string, number> { return just(this.b) .flatMap((numerator) => just(other) .flatMap((denominator) => denominator !== 0 ? right(numerator / denominator) : left('Division by zero') ) ) .getOrElse(left('Invalid input')); } } // Example usage const triple = Triple.of(1, 2, 3); const result = triple.map((x) => x * 2); console.log(result); // Triple { a: 2, b: 4, c: 6 } const divisionResult = triple.divideBy(2); console.log(divisionResult); // Either.Right { value: 1 } const invalidDivisionResult = triple.divideBy(0); console.log(invalidDivisionResult); // Either.Left { value: 'Division by zero' }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_python_pydantic_pymonad">Python, pydantic, pymonad</h2> <div class="sectionbody"> <div class="paragraph"> <p>Python을 사용하여 구현을 만들려면`pydantic`타입 검증 및`pymonad`모나드들을 위해:</p> </div> <div class="paragraph"> <p>의존성을 설치:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">pip install pydantic pymonad</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-python hljs" data-lang="python">from pymonad.either import Either, Left, Right from pydantic import BaseModel, ValidationError, validator # Définition de la classe Triple avec Pydantic class Triple(BaseModel): a: int b: int c: int @validator('b') def validate_b(cls, b, values): if b == 0: raise ValueError('Division by zero is not allowed') return b # Méthode utilisant Either pour la gestion des erreurs def divide_by(self, other): def division(numerator, denominator): return Right(numerator / denominator) def handle_error(error): return Left(str(error)) return Either(lambda: division(self.b, other)).or_else(handle_error) # Exemple d'utilisation try: triple = Triple(a=1, b=2, c=3) result = triple.divide_by(2) if result.is_right: print(f'Division result: {result.value}') else: print(f'Error: {result.value}') except ValidationError as e: print(f'Validation Error: {e}') except Exception as e: print(f'An unexpected error occurred: {e}')</code></pre> </div> </div> <div class="ulist"> <div class="title">이 예시에서 :</div> <ul> <li> <p><code>pydantic`클래스를 정의하기 위해`Triple`타입이 지정된 필드가 있는. - 방법`divide_by`모나드를 사용합니다`Either</code> de `pymonad`0으로 나누기 결과 발생할 수 있는 오류를 처리하기 위해 - 맞춤형 검증을 통해 값이`b`0이 아닙니다. 만약 0이라면 예외가 발생하고, 그리고`pymonad`이 예외를 잡아서 결과를 반환`Left`오류를 나타내고.</p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2023/0068_introduction_google_apps_script_post.html Fri, 22 Dec 2023 00:00:00 +0000 blog/2023/0068_introduction_google_apps_script_post.html <div class="sect1"> <h2 id="_목차">목차</h2> <div class="sectionbody"> <div class="paragraph"> <p><em>읽는 데 걸리는 시간 : 30분</em></p> </div> <div class="ulist"> <ul> <li> <p><a href="#서론">[서론]</a></p> </li> <li> <p>Google Apps Script 기본 구조</p> </li> <li> <p><a href="#_google_apps_script의_타입_및_변수">Google Apps Script의 타입 및 변수</a></p> </li> <li> <p>상수, 변수 및 Google Apps Script의 문자</p> </li> <li> <p><a href="#Google Apps Script의 연산과 연산자">[Google Apps Script의 연산과 연산자]</a></p> </li> <li> <p><a href="#Google Apps Script의 Var">Let, Const</a></p> </li> <li> <p><a href="#구글 앱스 스크립트의 제어 구조">[구글 앱스 스크립트의 제어 구조]</a></p> </li> <li> <p>Google Apps Script에서의 루프</p> </li> <li> <p><a href="#_google_apps_script의_객체">Google Apps Script의 객체</a></p> </li> <li> <p>Google Apps Script의 함수</p> </li> <li> <p>Google Apps Script의 매개변수와 스코프</p> </li> <li> <p><a href="#_google_apps_script의_rest_및_spread_연산자">Google Apps Script의 Rest 및 Spread 연산자</a></p> </li> <li> <p><a href="#Google Apps Script에서의 비구조화 할당">[Google Apps Script에서의 비구조화 할당]</a></p> </li> <li> <p>Google Apps Script의 컬렉션 및 선언적 프로그래밍</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_서론">서론</h2> <div class="sectionbody"> <div class="paragraph"> <p>Google Apps Script(GAS)는 Google Sheets, Google Docs, Google Forms과 같은 다양한 Google 서비스와 연관된 스크립트 개발 플랫폼입니다. 이를 통해 작업을 자동화하고 맞춤형 기능을 추가하며 Google 서비스를 통합할 수 있습니다.</p> </div> <div class="paragraph"> <p>이 메모에서는 구체적인 예를 바탕으로 Google Apps Script의 주요 개념을 탐구합니다. 변수, 루프, 함수 등 다양한 개념을 다루며, 이를 GAS의 특정 맥락에 맞게 적용할 것입니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_google_apps_script의_기본_구조">Google Apps Script의 기본 구조</h2> <div class="sectionbody"> <div class="paragraph"> <p>시작하기 전에, Google Apps Script의 기본 구조를 살펴봅시다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">/** * Structure de base en Google Apps Script */ function exempleStructureGAS() { // Votre code ici Logger.log("Hello, Google Apps Script!"); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_google_apps_script의_타입_및_변수">Google Apps Script의 타입 및 변수</h2> <div class="sectionbody"> <div class="paragraph"> <p>Google Apps Script는 프로그래밍 언어로 JavaScript를 사용합니다. 데이터 유형과 변수는 표준 JavaScript와 유사하게 동작합니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">/** * Types et Variables en Google Apps Script */ function exempleTypesVariablesGAS() { // Votre code ici var nombre = 42; var texte = "Bonjour, Google Apps Script!"; Logger.log(nombre); Logger.log(texte); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_작업_및_연산자_google_apps_script에서">작업 및 연산자 Google Apps Script에서</h2> <div class="sectionbody"> <div class="paragraph"> <p>Google Apps Script의 연산과 연산자는 JavaScript와 동일합니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">/** * Opérations et Opérateurs en Google Apps Script */ function exempleOperationsGAS() { // Votre code ici var x = 10; var y = 5; var resultat = x + y; Logger.log(resultat); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_google_apps_script에서_var_let_및_const">Google Apps Script에서 Var, Let 및 Const</h2> <div class="sectionbody"> <div class="paragraph"> <p>GAS에서는 개념의`var`, <code>let</code>, et `const`변수를 선언하는 데 사용됩니다. 그러나, 차이점과 영향을 이해하는 것이 필수적입니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">/** * Var, Let et Const en Google Apps Script */ function exempleVarLetConstGAS() { // Votre code ici // Utilisation de var var x = 10; if (true) { var x = 20; // La variable x est modifiée globalement } Logger.log(x); // Utilisation de let let y = 30; if (true) { let y = 40; // La variable y est limitée au bloc if } Logger.log(y); // Utilisation de const const z = 50; // z = 60; // Impossible de réassigner une constante Logger.log(z); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_google_apps_script의_제어_구조">Google Apps Script의 제어 구조</h2> <div class="sectionbody"> <div class="paragraph"> <p>제어 구조는 예를 들어`if`, <code>else</code>, <code>while</code> et `for`이것들은 Google Apps Script에서 실행 흐름을 관리하는 데 사용됩니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">/** * Structures de Contrôle en Google Apps Script */ function exempleStructuresControleGAS() { // Votre code ici var condition = true; if (condition) { Logger.log("La condition est vraie."); } else { Logger.log("La condition est fausse."); } var compteur = 0; while (compteur < 5) { Logger.log(compteur); compteur++; } for (var i = 0; i < 3; i++) { Logger.log(i); } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_google_apps_script에서_매개변수_및_스코프">Google Apps Script에서 매개변수 및 스코프</h2> <div class="sectionbody"> <div class="paragraph"> <p>매개변수와 스코프는 GAS에서 스크립트 개발에서 중요한 역할을 합니다. 어떻게 작동하는지 이해하여 예기치 않은 동작을 피하세요.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">/** * Paramètres et Scopes en Google Apps Script */ function exempleParametresScopesGAS(parametre) { // Votre code ici var variableGlobale = "Je suis global"; function afficherParametre() { Logger.log(parametre); } afficherParametre(); Logger.log(variableGlobale); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_google_apps_script에서_상수_변수_및_문자">Google Apps Script에서 상수, 변수 및 문자</h2> <div class="sectionbody"> <div class="paragraph"> <p>차이점을 이해하는`const`, <code>var</code>, et `let`은(는) Google Apps Script에서 변수의 효과적인 사용에 필수적입니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">/** * Constantes, Variables, et Lettres en Google Apps Script */ function exempleConstantesVariablesLettresGAS() { // Votre code ici const constante = "Je ne change pas"; Logger.log(constante); var variable = "Je peux changer"; Logger.log(variable); let lettre = "Je peux aussi changer, mais seulement dans mon bloc"; Logger.log(lettre); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_구글_앱스_스크립트에서의_반복문">구글 앱스 스크립트에서의 반복문</h2> <div class="sectionbody"> <div class="paragraph"> <p>루프, 예를 들어`for` et `while`요소를 반복하고 반복적인 작업을 수행하는 데 필수적입니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">/** * Boucles en Google Apps Script */ function exempleBouclesGAS() { // Votre code ici for (var i = 0; i < 3; i++) { Logger.log(i); } var condition = true; var compteur = 0; while (condition) { Logger.log("Tour de boucle"); compteur++; if (compteur === 3) { condition = false; } } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_google_apps_script의_객체">Google Apps Script의 객체</h2> <div class="sectionbody"> <div class="paragraph"> <p>객체는 데이터를 구조화하는 데 사용됩니다. GAS에서는 많은 내장 객체가 Google 서비스와의 상호작용을 용이하게 합니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">/** * Objets en Google Apps Script */ function exempleObjetsGAS() { // Votre code ici var feuille = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet(); var cellule = feuille.getRange("A1"); cellule.setValue("Nouvelle valeur"); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_google_apps_script에서_상수_변수_그리고_문자">Google Apps Script에서 상수, 변수, 그리고 문자</h2> <div class="sectionbody"> <div class="paragraph"> <p>차이를 이해하는`const`, <code>var</code>, et `let`이는 Google Apps Script에서 변수의 효율적인 사용에 필수적입니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">/** * Constantes, Variables, et Lettres en Google Apps Script */ function exempleConstantesVariablesLettresGAS() { // Votre code ici const constante = "Je ne change pas"; Logger.log(constante); var variable = "Je peux changer"; Logger.log(variable); let lettre = "Je peux aussi changer, mais seulement dans mon bloc"; Logger.log(lettre); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_google_apps_script의_함수">Google Apps Script의 함수</h2> <div class="sectionbody"> <div class="paragraph"> <p>함수는 프로그래밍의 기본 요소입니다. GAS에서는 다양한 방법으로 선언하고 호출할 수 있습니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">/** * Fonctions en Google Apps Script */ function exempleFonctionsGAS() { // Votre code ici function additionner(a, b) { return a + b; } var resultat = additionner(2, 3); Logger.log(resultat); // Fonction anonyme var multiplier = function (x, y) { return x * y; }; Logger.log(multiplier(4, 5)); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_google_apps_script의_rest_및_spread_연산자">Google Apps Script의 Rest 및 Spread 연산자</h2> <div class="sectionbody"> <div class="paragraph"> <p>휴식 연산자 (<code>…​</code>) 그리고 의 전파 (<code>…​</code>)는 배열과 객체를 간결하게 조작하는 데 유용합니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">/** * Opérateurs de Repos et de Propagation en Google Apps Script */ function exempleOperateursReposPropagationGAS() { // Votre code ici // Opérateur de repos (...) pour les tableaux var nombres = [1, 2, 3, 4, 5]; var [...copieNombres] = nombres; Logger.log(copieNombres); // Opérateur de propagation (...) pour les objets var objOriginal = { x: 1, y: 2 }; var objClone = { ...objOriginal, z: 3 }; Logger.log(objClone); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_google_apps_script의_분해_할당">Google Apps Script의 분해 할당</h2> <div class="sectionbody"> <div class="paragraph"> <p>구조 해체 할당은 값들을 객체와 배열에서 간결하게 추출할 수 있게 해주는 강력한 기능입니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">/** * Affectation par Décomposition en Google Apps Script */ function exempleAffectationDecompositionGAS() { // Votre code ici var coordonnees = [3, 4]; var [x, y] = coordonnees; Logger.log(x); Logger.log(y); var utilisateur = { nom: "John", age: 30 }; var { nom, age } = utilisateur; Logger.log(nom); Logger.log(age); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_google_apps_script에서의_컬렉션_및_선언적_프로그래밍">Google Apps Script에서의 컬렉션 및 선언적 프로그래밍</h2> <div class="sectionbody"> <div class="paragraph"> <p>Google Apps Script은 배열과 같은 데이터 구조를 지원하며, 함수형 프로그래밍과 선언적 반복(명령형 대비)과 같은`map`, <code>reduce</code> et <code>forEach</code>.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">/** * Collections et Programmation Déclarative en Google Apps Script */ function exempleCollectionsFonctionnelleGAS() { // Votre code ici // Exemple de tableau (collection) var nombres = [1, 2, 3, 4, 5]; // Utilisation de forEach nombres.forEach(function (nombre) { Logger.log(nombre); }); // Utilisation de map var carresNombres = nombres.map(function (nombre) { return nombre * nombre; }); Logger.log(carresNombres); // Utilisation de reduce var somme = nombres.reduce(function (acc, nombre) { return acc + nombre; }, 0); Logger.log(somme); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_결론">결론</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 메모는 구체적인 코드 예시를 통해 Google Apps Script의 기본 개념을 다뤘습니다. 이 지식을 활용하여 일상적인 작업을 자동화하고, 문서를 맞춤 설정하며, Google Apps Script의 기능을 최대한 활용하세요.</p> </div> </div> </div> https://cheroliv.com/blog/2023/0067_formation_express_sur_google_forms_script_post.html Wed, 20 Dec 2023 00:00:00 +0000 blog/2023/0067_formation_express_sur_google_forms_script_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>시간: 30분</p> </div> </div> </div> <div class="sect1"> <h2 id="_목표">목표</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Forms에서 Google Apps Script 기초 이해하기 - 스크립트 편집기에 접근하고 트리거에서 명령을 실행하는 방법을 배우다</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_지연">지연</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Google Form 스크립트 소개</strong>(5분)</p> <div class="ulist"> <ul> <li> <p>Google Form Script 빠른 개요 - 주요 기능 소개</p> </li> </ul> </div> </li> <li> <p><strong>Google 폼 생성 및 연결된 스크립트</strong>(5 분)</p> <div class="ulist"> <ul> <li> <p>Google Forms로 간단한 양식 만들기 - 연관된 스크립트 편집기 소개</p> </li> </ul> </div> </li> <li> <p><strong>명령을 실행</strong>(10분)</p> <div class="ulist"> <ul> <li> <p>"on start" 트리거 구성 - "on submit" 트리거 구성 - 명령을 실행하기 위한 스크립트 작성 - 빠른 테스트를 수행하여 일지에서 정상 작동을 확인합니다</p> </li> </ul> </div> </li> <li> <p><strong>결과 분석 및 우수 사례</strong>(10분)</p> <div class="ulist"> <ul> <li> <p>명령어 실행 결과 검증 스크립트 예시와 자동화가 시간을 절약할 수 있는 방법에 대한 논의</p> </li> </ul> </div> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_선수_조건">선수 조건</h2> <div class="sectionbody"> <div class="paragraph"> <p>Google 계정이 있어야 하며, Google Forms와 Google Sheets에 접근할 수 있어야 합니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_장비">장비</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>웹 브라우저와 인터넷 연결이 있는 컴퓨터</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_주석">주석</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 빠른 교육은 Google Form Script를 사용한 자동화에 대한 빠른 소개를 제공합니다. 더 깊은 이해를 위해서는 더 긴 교육이 권장됩니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_1_google_form_스크립트_소개">1 - Google Form 스크립트 소개</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_slide_1_google_form_script_빠른_개요">Slide 1: Google Form Script 빠른 개요</h3> <div class="ulist"> <ul> <li> <p>Google Form Script는 Google Forms에 통합된 스크립팅 플랫폼입니다. - 그녀는 맞춤형 기능을 추가하고 작업을 자동화할 수 있습니다.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_슬라이드_2_주요_기능_소개">슬라이드 2: 주요 기능 소개</h3> <div class="ulist"> <ul> <li> <p>Script Editor : Google Apps Script를 작성하기 위한 내장 스크립트 편집기. - 트리거: "on submit"과 같은 이벤트가 스크립트 실행을 활성화합니다.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_슬라이드_3_google_form_script_사용의_장점">슬라이드 3: Google Form Script 사용의 장점</h3> <div class="ulist"> <ul> <li> <p>맞춤형 : 고유한 기능을 갖춘 맞춤형 양식을 만드세요. - 자동화 : 폼 응답에 따라 작업을 자동화하세요. - 통합: 다른 Google 서비스와 스크립트를 통합하여 보다 풍부한 경험을 제공합니다.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_발표자를_위한_메모">발표자를 위한 메모:</h3> <div class="paragraph"> <p>이러한 기능은 양식을 맞춤 설정하고 자동화하는 데 상당한 잠재력을 제공합니다. 이 과정의 다음 부분에서는 스크립트 및 특정 자동화의 생성에 대해 자세히 살펴볼 것입니다.</p> </div> <div class="paragraph"> <p><a href="https://developers.google.com/apps-script/add-ons/editors/forms?hl=fr" class="bare">https://developers.google.com/apps-script/add-ons/editors/forms?hl=fr</a></p> </div> <div class="paragraph"> <p><a href="https://developers.google.com/apps-script/reference/forms?hl=fr" class="bare">https://developers.google.com/apps-script/reference/forms?hl=fr</a></p> </div> <div class="paragraph"> <p><a href="https://developers.google.com/apps-script/reference/forms/form-app?hl=fr" class="bare">https://developers.google.com/apps-script/reference/forms/form-app?hl=fr</a></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_google_폼과_연관된_스크립트_생성_5분"><strong>Google 폼과 연관된 스크립트 생성</strong> (5분)</h2> <div class="sectionbody"> </div> </div> https://cheroliv.com/blog/2023/0066_memo_python_post.html Sun, 19 Nov 2023 00:00:00 +0000 blog/2023/0066_memo_python_post.html <div class="sect1"> <h2 id="_windows에_python_설치">Windows에 Python 설치</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://ninite.com/pythonx3/">윈도우에서 파이썬</a></p> </div> <div class="paragraph"> <p><a href="https://python-docs.readthedocs.io/en/latest/starting/install3/win.html" class="bare">https://python-docs.readthedocs.io/en/latest/starting/install3/win.html</a></p> </div> <div class="paragraph"> <p><a href="https://python-docs.readthedocs.io/en/latest/dev/virtualenvs.html#virtualenvironments-ref" class="bare">https://python-docs.readthedocs.io/en/latest/dev/virtualenvs.html#virtualenvironments-ref</a></p> </div> </div> </div> <div class="sect1"> <h2 id="_파이썬_실행_중">파이썬 실행 중</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">문제점: Python venv</div> <p>참조 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">cd mon_projet python -m venv mon_venv source mon_venv/bin/activate # Sur windows mon_venv\Scripts\activate deactivate</code></pre> </div> </div> <div class="sect2"> <h3 id="_설치_요구사항">설치 요구사항</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">pip install -r requirements.txt</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_입문">입문</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://python.doctor/page-apprendre-programmation-orientee-objet-poo-classes-python-cours-debutants">파이썬 객체 지향 프로그래밍</a></p> </div> </div> </div> <div class="sect1"> <h2 id="_파이썬에서의_gof_디자인_패턴">파이썬에서의 GoF 디자인 패턴</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://github.com/whikwon/python-patterns/">구현 1</a></p> </div> <div class="paragraph"> <p><a href="https://github.com/Sean-Bradley/Design-Patterns-In-Python">구현 2</a></p> </div> <div class="paragraph"> <p><a href="https://sbcode.net/python/">완전한 책</a></p> </div> <div class="paragraph"> <p>GoF 디자인 패턴은 《Design Patterns: Elements of Reusable Object-Oriented Software》이라는 책에 기술된 23가지 디자인 패턴의 집합입니다.</p> </div> <table class="tableblock frame-all grid-all stretch"> <caption class="title">Table 1. 여기 GoF 디자인 패턴 목록이 있습니다.</caption> <colgroup> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0849%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">이름</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">설명</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>팩토리 메서드</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">정확한 클래스를 지정하지 않고 객체를 생성합니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>추상 팩토리</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">구체적인 클래스를 지정하지 않고 관련되거나 의존적인 객체들의 가족을 만듭니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>건설업자</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">복잡한 객체의 구축을 그 객체의 표현에서 분리하여, 동일한 구축 과정으로 서로 다른 표현을 만들 수 있게 한다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>프로토타입</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">기존 프로토타입을 복사하여 새 객체를 만든다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Singleton</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">클래스의 인스턴스화를 하나의 객체로 제한합니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>어댑터</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">클래스의 인터페이스를 클라이언트가 기대하는 다른 인터페이스로 변환합니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>브리지</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">추상화를 구현으로부터 분리하여 두 가지가 독립적으로 변하도록 한다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>복합</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">트리 구조에 객체를 구성하여 부분-전체 계층 구조를 표현합니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>데코레이터</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">객체에 동적으로 추가적인 책임을 연결합니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>정면</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">하위 시스템에 있는 인터페이스 집합에 대한 통합 인터페이스를 제공합니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>플라이웨이트</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">가벼운 객체 생성 및 사용 비용을 줄입니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>프록시</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">다른 개체에 대한 액세스를 제어하기 위해 대체물 또는 자리 표시자를 제공합니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>책임 연쇄</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">두 개 이상의 객체가 요청을 처리할 수 있게 한다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>명령</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">요청을 객체에 캡슐화함으로써 다양한 요청, 큐 또는 로그를 가진 클라이언트를 매개변수화하고, 취소 가능한 작업을 지원할 수 있습니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>통역사</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">언어의 문법 표현을 제공하고, 이 표현을 사용하여 해당 언어의 문장을 해석한다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>이터레이터</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">집계 객체의 요소들을 순차적으로 탐색할 수 있는 방법을 제공하면서, 내부 표현을 노출하지 않습니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>중재자</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">객체 간 복잡한 의존성을 중재자 객체를 통해서만 통신하도록 함으로써 줄일 수 있습니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>메멘토</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">이전 상태로 객체를 복원할 수 있는 기능을 제공합니다(캡슐화를 위반하지 않고).</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>관찰자</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">객체 간의 일대다 의존성을 정의하여, 객체의 상태가 변경되면 모든 종속 객체에 자동으로 알림이 전송되고 업데이트됩니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>상태</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">객체가 내부 상태가 변경될 때 행동을 변경할 수 있게 합니다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>전략</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">알고리즘 가족을 정의하고, 각각을 캡슐화하여 교환 가능하게 만든다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>템플릿 메서드</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">메서드 내에서 알고리즘의 골격을 정의하고, 일부 단계는 서브클래스로 위임한다.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>방문자</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">객체 구조에 새로운 연산을 정의할 수 있게 하며, 해당 연산을 수행하는 객체의 클래스를 변경하지 않고 수행한다.</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_함수형_프로그래밍">함수형 프로그래밍</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 16.6666%;"> <col style="width: 27.7777%;"> <col style="width: 55.5557%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">도서관</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">URL</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">설명</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">PyMonad</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://github.com/jasondelaat/pymonad" class="bare">https://github.com/jasondelaat/pymonad</a></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">PyMonad는 Haskell 및 F#과 같은 프로그래밍 언어를 기반으로 한 Python의 모나딕 데이터 구조 구현으로, 함수형 프로그래밍에서 가장 일반적으로 사용되는 모나드 유형에 대한 구현을 제공합니다.https://www.miguelfarrajota.com/2021/06/monads-in-python-with-pymonad/[기사]</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">파이펑셔널</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://github.com/EntilZha/PyFunctional/" class="bare">https://github.com/EntilZha/PyFunctional/</a></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">PyFunctional은 함수형 프로그래밍을 위한 파이썬 라이브러리로, 순수 함수와 이터러블을 다루기 위한 도구를 제공합니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">툴즈</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://toolz.readthedocs.io/en/latest/" class="bare">https://toolz.readthedocs.io/en/latest/</a></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Toolz는 순수 함수와 이터러블을 다루는 데 사용할 수 있는 도구를 제공하는 함수형 프로그래밍을 위한 Python 라이브러리이다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Fn.py</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://github.com/kachayev/fn.py" class="bare">https://github.com/kachayev/fn.py</a></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Fn.py는 순수 함수와 이터러블 작업에 사용할 도구를 제공하는 함수형 프로그래밍을 위한 Python 라이브러리입니다.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">코코넛</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://coconut-lang.org/" class="bare">https://coconut-lang.org/</a></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Coconut은 함수형 프로그래밍을 위해 Python에 여러 가지 기능을 추가하며, 여기에는 패턴 매칭도 포함됩니다.https://stackoverflow.com/questions/11909681/are-there-pattern-matching-functions-in-python-like-this[대화 소프]</p></td> </tr> </tbody> </table> <div class="sect2"> <h3 id="_부작용">부작용</h3> </div> <div class="sect2"> <h3 id="_루프">루프</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-python hljs" data-lang="python"># impérative way result = [] for i in inputs: x = f(g(i)) result.append(x) # idiomatic way result = map(comp(f,g), inputs)</code></pre> </div> </div> </div> </div> </div> https://cheroliv.com/blog/2023/0065_training_web_dev_post.html Thu, 24 Aug 2023 00:00:00 +0000 blog/2023/0065_training_web_dev_post.html https://cheroliv.com/blog/2023/0064_training_trading_card_games_post.html Mon, 21 Aug 2023 00:00:00 +0000 blog/2023/0064_training_trading_card_games_post.html https://cheroliv.com/blog/2023/0063_memo_ts_post.html Sat, 19 Aug 2023 00:00:00 +0000 blog/2023/0063_memo_ts_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>github 저장소:https://github.com/cheroliv/ts-codebase[ts-codebase, window="_blank]</p> </div> </div> </div> <div class="sect1"> <h2 id="toc_ts"><span class="underline">Intro typescript</span></h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#ts_types">타입스크립트의 타입</a></p> </li> <li> <p><a href="#함수">함수</a></p> </li> <li> <p></think></p> </li> <li> <p><a href="#enums_tuples">열거형과 튜플</a></p> </li> <li> <p><a href="#void_never">Void과 Never</a></p> </li> <li> <p><a href="#class_interface">클래스와 인터페이스</a></p> </li> <li> <p><a href="#tsconfig">tsconfig.json 파일</a></p> </li> <li> <p><a href="#modules">모듈</a></p> </li> <li> <p>약속들</p> </li> <li> <p><a href="#async-await">async/await</a></p> </li> <li> <p><a href="#제네릭">[제네릭]</a></p> </li> </ol> </div> <div class="paragraph"> <p>index.html</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta http-equiv="X-UA-Compatible" content="ie=edge" /> <title>Document</title> </head> <body> Intro typescript <script src="01_types.js"></script> <script src="02_data_structure.js"></script> <script src="03_enums_tuples.js"></script> </body> </html></code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="ts_types">타입스크립트의 타입</h2> <div class="sectionbody"> <div class="paragraph"> <p>01_types.ts</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-typescript hljs" data-lang="typescript">/** * Les types en typescript */ //quand le type n'est pas defini des le debut, // alors il est réassignable // c'est le type Any qui est attribué par défaut let my_var; my_var = "username"; console.assert(my_var === "username"); my_var = 11; console.assert(my_var === 11); my_var = true; console.assert(my_var === true); let age = 1; console.assert(age === 1); age = 2; // age="trois" c'est impossible // car l'inference de type a attribué le type number console.assert(age === 2); // Déclaration explicite de type let pi: Number = 3.14; console.assert(typeof pi === "number");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="함수">함수</h2> <div class="sectionbody"> <div class="paragraph"> <p>함수는 재사용 가능한 코드 블록입니다.</p> </div> <div class="paragraph"> <p>예시 점수 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-typescript hljs" data-lang="typescript">const add = (a: number, b: number): number => a + b;</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="data_struct">데이터 구조</h2> <div class="sectionbody"> <div class="paragraph"> <p>02_data_structure.ts</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-typescript hljs" data-lang="typescript">/*** * Structure de données: * Avec le type any on peut changer * le type de la variable à tout instruction * Lorsque l'on fixe le type * alors il n'est plus possible de le changer * lors d'une assignation */ // Arrays let buddies: any[] = [ "cheroliv", "imrandeh", "issoudeh", "soumi92" ] console.assert(buddies[0] === "cheroliv"); console.assert(buddies[1] === "imrandeh"); console.assert(buddies[2] === "issoudeh"); console.assert(buddies[3] === "soumi92"); // Déclaré en type any, l'inference de type // a bien réaligné en type string console.assert(typeof buddies[0] === "string"); console.assert(typeof buddies[1] === "string"); console.assert(typeof buddies[2] === "string"); console.assert(typeof buddies[3] === "string"); let writers: (String | String | String | Number)[][] = [ ["Chrétien", "de Troyes", "fr", 12], ["François", "Rabelais", "fr", 16], ["René", "Descartes", "fr", 17], ["Jean-Jacques", "Rousseau", "fr", 18], ["Georg", "Hegel", "de", 19], ["Karl", "Marx", "de", 19], ["Friedrich", "Engels", "de", 19], ["Victor", "Hugo", "fr", 19], ["Paul", "Verlaine", "fr", 19], ["Arthur", "Rimbaud", "fr", 19], ["Gérard", "de Nerval", "fr", 19], ["Georg", "Lukacs", "hu", 20], ["Franz", "Kafka", "hu", 20], ["Antonio", "Gramsci", "it", 20], ["Domenico","Losurdo","it",20], ]; // console.table(writers); // Objects let author: { first_name: String, last_name: String, lang: String, century: Number } = { // slice(-1) renvoie le dernier élèment first_name: writers.slice(-1)[0][0] as String, last_name: writers.slice(-1)[0][1] as String, lang: writers.slice(-1)[0][2] as String, century: writers.slice(-1)[0][3] as Number, } // assertion sur la valeur en accés par encapsulation(dot) console.assert(author.first_name === "Antonio") console.assert(author.last_name === "Gramsci") console.assert(author.lang === "it") console.assert(author.century === 20); // assertion sur le type en accès par index console.assert(typeof author["first_name"] === "string") console.assert(typeof author["last_name"] === "string") console.assert(typeof author["lang"] === "string") console.assert(typeof author["century"] === "number");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="enums_tuples">열거형과 튜플</h2> <div class="sectionbody"> <div class="paragraph"> <p>03_enums_tuples.ts</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-typescript hljs" data-lang="typescript">/** * Enums et Tuples * * Enum: il existe les enums numérique * et les enums chaine de caracteres. * * Tuple: similaire aux arrays mais ne peut * contenir qu'une valeur de type spécifié. * */ //Enum numérique // l'index par de debut défaut est 0 // ici on le place a 1 enum Week { Monday = 1, Tuesday = 2, Wednesday = 3, Thursday = 4, Friday = 5, Saturday = 6, Sunday = 7, }; console.assert(Week.Monday == 1); console.assert(Week.Tuesday == 2); console.assert(Week.Wednesday == 3); console.assert(Week.Thursday == 4); console.assert(Week.Friday == 5); console.assert(Week.Saturday == 6); console.assert(Week.Sunday == 7); console.assert(Week[1] === "Monday"); console.assert(Week[2] === "Tuesday"); console.assert(Week[3] === "Wednesday"); console.assert(Week[4] === "Thursday"); console.assert(Week[5] === "Friday"); console.assert(Week[6] === "Saturday"); console.assert(Week[7] === "Sunday"); let motd_arr_fr: String[] = [ "Associé à la Lune", "Du dieu Tiw, associé à Mars", "Du dieu germanique Odin", "Du dieu germanique du tonnerre Thor", "De la déesse germanique Frigga associée à Vénus", "Associé à Saturne", "Associé au Soleil", ]; let motd_arr_en: String[] = [ "associated with the Moon", "from the god Tiw, associated with Mars", "from Germanic god Odin", "from Germanic god of thunder Thor", "from Germanic goddess Frigga associated with Venus", "associated with Saturn", "associated with the Sun", ]; // Un tuple (triple) let monday_triple_fr: [ Number, String, String ] = [ Week.Monday, Week[Week.Monday], motd_arr_fr[0], ]; console.assert(monday_triple_fr[0] === 1); console.assert(monday_triple_fr[1] === "Monday"); console.assert(monday_triple_fr[2] === "Associé à la Lune"); let monday_triple_en: [ Number, String, String ] = [ Week.Monday, Week[Week.Monday], motd_arr_en[0], ]; console.assert(monday_triple_en[0] === 1); console.assert(monday_triple_en[1] === "Monday"); console.assert(monday_triple_en[2] === "associated with the Moon"); // On se fait un type pour ajouter le nom de la langue type Meaning_of_the_day = { lang: String, meaning: (Week | String)[][], }; //fonction d'affichage du type Meaning_of_the_day const display_motd = (motd: Meaning_of_the_day) => { motd.meaning.forEach(day => console.table(`${Week[day[0] as Week]}: ${day[1]}.(${motd.lang})`) ) }; //fonction d'assertion sur le type Meaning_of_the_day // afin de verifier la concordance du contenu avec // motd_arr_#lang# const test_motd = ( motd: Meaning_of_the_day, motd_arr: String[] ) => { console.assert(motd.lang.length === 2) for (const [i, value] of motd.meaning.entries()) { console.assert(value[1] === motd_arr[i]); } }; let motd_fr: Meaning_of_the_day = { lang: "fr", meaning: [ [Week.Monday, motd_arr_fr[0]], [Week.Tuesday, motd_arr_fr[1]], [Week.Wednesday, motd_arr_fr[2]], [Week.Thursday, motd_arr_fr[3]], [Week.Friday, motd_arr_fr[4]], [Week.Saturday, motd_arr_fr[5]], [Week.Sunday, motd_arr_fr[6]], ], } console.log("---------"); console.log("display_motd(motd_fr):"); display_motd(motd_fr); test_motd(motd_fr, motd_arr_fr) let motd_en: Meaning_of_the_day = { lang: "en", meaning: [ [Week.Monday, motd_arr_en[0]], [Week.Tuesday, motd_arr_en[1]], [Week.Wednesday, motd_arr_en[2]], [Week.Thursday, motd_arr_en[3]], [Week.Friday, motd_arr_en[4]], [Week.Saturday, motd_arr_en[5]], [Week.Sunday, motd_arr_en[6]], ], } console.log("---------"); console.log("display_motd(motd_en):"); display_motd(motd_en); console.log("---------"); test_motd(motd_en, motd_arr_en); // Un tuple (triple) utilisant le type // Meaning_of_the_day pour peupler le meaning let motd_triple: [ Number, String, String ] = [ Week.Monday, Week[Week.Monday], motd_fr.meaning[0][1] as String ]; console.assert(motd_triple[0] === 1); console.assert(motd_triple[1] === "Monday"); console.assert(motd_triple[2] === "Associé à la Lune");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="void_never">Void과 Never</h2> <div class="sectionbody"> <div class="paragraph"> <p>04_void_never_types.ts</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-typescript hljs" data-lang="typescript">// Le type void est l'opposé du type any // c'est l'absence de type. function verify_writers_length(): void { console.assert(writers.length > 0); } verify_writers_length(); const verify_writers_length_arrow = (): void => console.assert(writers.length > 0); verify_writers_length_arrow(); //Type of et never let value = 30; console.assert(typeof value === "number"); //never: qqchs qui n'arrive jamais function foo(x: String | Number): Boolean { if (typeof x === "string") { return true; } else if (typeof x === "number") { return false; } return fail("Error!") } function fail(message: String): never { throw new Error(message as string); }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="class_interface">클래스와 인터페이스</h2> <div class="sectionbody"> <div class="paragraph"> <p>04_void_never_types.ts</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-typescript hljs" data-lang="typescript">/** * Les classes: * members, * visibility, * nommage, * accesseurs * scope identifier: static,private,protected * * convention de nommage : * Les membres private sont préfixés avec un _ * */ class Member { username: String = ""; email: String = ""; private _password: String = ""; readonly signup_date: Date = new Date(Date.now()); constructor(username: String, email: String) { this.username = username; this.email = email; } get password(): String { return this._password; } set password(new_password: String) { this._password = new_password; } /** * Une fonction static qui initilise un member, * à partir d'un author */ static fromAuthor(author: { first_name: String, last_name: String, lang: String, century: Number }): Member { return new Member( `${author.first_name}.${author.last_name}`, `${author.first_name}.${author.last_name}@acme.com`, ); } }; let domenico = Member.fromAuthor(author); domenico.password = "test"; console.assert(domenico.email === "Domenico.Losurdo@acme.com"); console.assert(domenico.password === "test"); // Héritage enum Forms { Undefined = 0, Polygones = 1, Circle = 2, Straight = 3, Segment = 4, }; class Form { type: Forms = Forms.Undefined; }; class Rectangle extends Form { h: Number = 0; w: Number = 0; }; class Square extends Rectangle { side: Number = 0; }; /** * Interface donne un contrat à un type. * Les interfaces permettent de définir la structure d'un objet. */ interface IPerson { username: String; email: String; readonly signup_date: Date; } const user1: IPerson = { username: Member.fromAuthor(author)["username"], email: Member.fromAuthor(author)["email"], signup_date: Member.fromAuthor(author)["signup_date"], }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="tsconfig">tsconfig.json 파일</h2> <div class="sectionbody"> <div class="paragraph"> <p>tsconfig.json</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{ /* Visit https://aka.ms/tsconfig to read more about this file */ "compileOnSave": true, "compilerOptions": { "target": "es2016", "module": "CommonJS", "noEmitOnError": true, "strict": true, "noImplicitAny": true, "esModuleInterop": true } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="modules">모듈</h2> <div class="sectionbody"> <div class="paragraph"> <p>모듈은 코드를 여러 파일로 구성할 수 있게 합니다.</p> </div> <div class="paragraph"> <p>점수 예시:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-typescript hljs" data-lang="typescript">// Dans un fichier math.ts export const add = (a: number, b: number): number => a + b; // Dans un autre fichier import { add } from './math'; let result = add(2, 3);</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id=""><a id="약속"></a></h2> <div class="sectionbody"> <div class="paragraph"> <p>프로미스는 비동기 작업을 수행하기 위해 사용됩니다.</p> </div> <div class="paragraph"> <p>예시 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-typescript hljs" data-lang="typescript">const promise = new Promise<string>((resolve) => { // Code asynchrone ici resolve("Succès"); }); promise.then((result) => { console.log(result); });</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="async-await">async/await</h2> <div class="sectionbody"> <div class="paragraph"> <p>async/await는 프로미스 관리를 간소화합니다.</p> </div> <div class="paragraph"> <p>예시: 점수</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-typescript hljs" data-lang="typescript">const fetchData = async (): Promise<void> => { const result = await someAsyncFunction(); console.log(result); };</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="generiques">제네릭</h2> <div class="sectionbody"> <div class="paragraph"> <p>제네릭은 동적 타입과 함께 재사용 가능한 구성 요소를 생성할 수 있게 합니다.</p> </div> <div class="paragraph"> <p>예시 점수:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-typescript hljs" data-lang="typescript">const identity = <T>(arg: T): T => arg; const output = identity<string>("hello"); console.log(output);</code></pre> </div> </div> </div> </div> https://cheroliv.com/blog/2023/0062_memo_css_post.html Mon, 14 Aug 2023 00:00:00 +0000 blog/2023/0062_memo_css_post.html <div class="sect1"> <h2 id="toc">목차</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#good_links">좋은 링크</a></p> </li> <li> <p><a href="#repo">리포지토리와 코드 샘플</a></p> </li> <li> <p><a href="#toc_시작">[toc_시작]</a></p> </li> </ol> </div> <div class="sect2"> <h3 id="good_links">좋은 링크</h3> <div class="paragraph"> <p><a href="#toc">목차</a></p> </div> </div> <div class="sect2"> <h3 id="repo">리포지토리와 코드 샘플</h3> <div class="paragraph"> <p>깃허브 저장소:https://github.com/cheroliv/css-codebase[css 코드베이스, 창 = "_blank]</p> </div> </div> <div class="sect2"> <h3 id="toc_début"><span class="underline">CSS 시작</span></h3> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#début_intro">소개 및 준비</a></p> </li> <li> <p><a href="#시작_텍스트">[시작_텍스트]</a></p> </li> <li> <p><a href="#시작_배경">[시작_배경]</a></p> </li> <li> <p><a href="#시작_박스">[시작_박스]</a></p> </li> <li> <p>시작</p> </li> <li> <p><a href="#시작_grid">[시작_grid]</a></p> </li> <li> <p><a href="#시작_abs_pos">[시작_abs_pos]</a></p> </li> <li> <p><a href="#시작_반응형">[시작_반응형]</a></p> </li> <li> <p><a href="#결론_시작">[결론_시작]</a></p> </li> </ol> </div> <div class="paragraph"> <p><a href="#toc">목차</a></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="début_intro">소개 및 준비</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 비디오를 기반으로 한 소개:</p> </div> <div class="videoblock"> <div class="content"> <iframe src="https://www.youtube.com/embed/iSWjmVcfQGg?rel=0" frameborder="0" allowfullscreen></iframe> </div> </div> <div class="paragraph"> <p>깃허브 저장소:https://github.com/cheroliv/css-codebase/début_css/[시작 CSS, window = "_blank]</p> </div> <div class="paragraph"> <p>memo source:<br> index.html</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Cours CSS</title> <link rel="stylesheet" href="style.css" /> </head> <body> <header> <h1>Les bases de CSS</h1> </header> <main> <div class="flexbox"> <h2>Flexbox</h2> <ul> <li>boite 1</li> <li>boite 2</li> <li>boite 3</li> </ul> </div> <div class="grid"> <h2>Grid</h2> <div class="grid-container"> <img src="./assets/img/css-logo.png" alt="logo css" /> <form action=""> <input type="text" id="firstname" placeholder="Prénom" /> <input type="text" id="surname" placeholder="Nom" /> <textarea cols="30" rows="10" placeholder="Ici votre message" ></textarea> <input type="submit" value="Valider" id="btn-submit" /> </form> </div> </div> <div class="absolute"> <h2>Absolute</h2> <span id="circle1"></span> <span id="circle2"></span> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p>html 페이지에 style.css 파일을 연결:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"></head> <link rel="stylesheet" href="style.css" /> </head></code></pre> </div> </div> <div class="paragraph"> <p><a href="#목차 시작">[목차 시작]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_texts">텍스트</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">/* import remote de font sur l'ensemble de la feuille*/ @import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); /* import local de font */ @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } /* body est le parent de toutes les balises, qu'il contient, donc je le déclare avant, pour la logique de précédence de parent */ body { /* si DMSerif n'est pas trouvé alors il se rabat sur Verdana*/ font-family: "DMSerif", Verdana; } /* va styliser toutes les balises h1, celles de body sont surchargés, par la déclaration présente */ h1 { text-transform: uppercase; /* espacement entre les lettres en pixel*/ letter-spacing: 3px; /* alignement du texte*/ text-align: center; /* Les tailles de polices doivent être en REM (rem = root em). Le REM se base pas sur l'élément parent pour obtenir sa taille mais sur l'élément racine. Ainsi 1rem prendra sa valeur de la font-size de votre document (body ou html).*/ font-size: 2.5rem; /* ombrage du texte */ text-shadow: 3px /* offset-x */ 3px /* offset-y */ 8px /* blur-radius */ #00000042/* color */; /* couleur du texte */ color: #ab0ef4; /*attibuer les polices(font): liste, ordonnée par priorité, de polices à utiliser pour mettre en forme le texte de l'élément ciblé.*/ font-family: "Oswald", sans-serif; /* surligner le text*/ text-decoration: underline; }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#목차 시작">[목차 시작]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_background">배경</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } body { font-family: "DMSerif", Verdana; /* image comme background*/ background: url(./assets/img/bg.jpg) center/cover; /* 100VH = 100% de la taille de l'écran (viewport height) min afin de ne pas bloquer la possibilité d'avoir un plus grand */ min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_시작">[toc_시작]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="시작_boxes">상자들 (boxes)</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } /* *: létoile donne du style a tous les éléments. Ensuite remettre un à un les parametres par defaut afin d'eviter les stylisation inattendu.*/ * { /* surcharge de base tous les elements à padding 0*/ margin: 0; /* surcharge de base tous les elements à padding 0*/ padding: 0; } body { font-family: "DMSerif", Verdana; /* image comme background*/ background: url(./assets/img/bg.jpg) center/cover; min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; } main { background: rgba(245, 245, 245, 0.9); min-height: 500px; /* quelque soit la taille de l'écran, la boite fait toujours 90% de la taille de la page, les 10% restant sont une marge à droite, pour avoir 5% de chaque coté on ajoute une margin, tel que [0, auto]*/ width: 90%; /* haut bas prend 0, et gauche droite prend auto(center cad meme de chaque cotés)*/ margin: 0 auto; /* on ajoute des bords a notre boite*/ border: 2px solid rgb(0, 140, 255); /* on arrondis les coins de la boite*/ border-radius: 20px 20px 0 0; /* ombrage sur la boite*/ box-shadow: 0px 0px 20px 4px #81cfc6; /* marge interrieure de la boite sur tous les cotés*/ padding: 15px; } h2 { /* afin de recuprer le comportement par defaut qui a ete surchargé par l'operateur étoile*/ margin: 0; }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Cours CSS</title> <link rel="stylesheet" href="style.css" /> </head> <body> <header> <h1>Les bases de CSS</h1> </header> <main> <div class="flexbox"> <h2>Flexbox</h2> <ul> <li>boite 1</li> <li>boite 2</li> <li>boite 3</li> </ul> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#목차_시작">[목차_시작]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_flexbox">플렉스박스</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } body { font-family: "DMSerif", Verdana; background: url(./assets/img/bg.jpg) center/cover; min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; } main { background: rgba(245, 245, 245, 0.9); min-height: 500px; width: 90%; margin: 0 auto; border: 2px solid rgb(0, 140, 255); border-radius: 20px 20px 0 0; box-shadow: 0px 0px 20px 4px #81cfc6; padding: 15px; } h2 { margin: 0; } /* le point permet d'acceder à la classe d'un composant*/ .flexbox { border: 2px solid skyblue; border-radius: 10px; padding: 10px; margin-top: 20px; min-height: 150px; } /* FLEXBOX */ /* Sert à répartir équitablement des éléments sur la page */ .flexbox ul { padding: 0; /* aligne les éléments enfants de ul(les li)*/ display: flex; /* reparti convenablement(équitablement les li sur la page) */ justify-content: space-around; } /* ce style concerne les li de la classe, flexbox des balises qui y font referencent*/ .flexbox li { /* suprime les boules des éléments de la list li*/ list-style: none; height: 160px; width: 160px; margin: 10px; background: turquoise; /* Centrer un unique élément verticalement et horizontalement */ display: flex; justify-content: center; align-items: center; }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Cours CSS</title> <link rel="stylesheet" href="style.css" /> </head> <body> <header> <h1>Les bases de CSS</h1> </header> <main> <div class="flexbox"> <h2>Flexbox</h2> <ul> <li>boite 1</li> <li>boite 2</li> <li>boite 3</li> </ul> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#목차_시작">[목차_시작]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_grid">그리드</h2> <div class="sectionbody"> <div class="paragraph"> <p>플렉스박스보다 조금 더 복잡한 방식으로 요소들을 분배하려면 그리드 시스템 등을 사용할 수 있습니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } body { font-family: "DMSerif", Verdana; background: url(./assets/img/bg.jpg) center/cover; min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; } main { background: rgba(245, 245, 245, 0.9); min-height: 500px; width: 90%; margin: 0 auto; border: 2px solid rgb(0, 140, 255); border-radius: 20px 20px 0 0; box-shadow: 0px 0px 20px 4px #81cfc6; padding: 15px; } h2 { margin: 0; } .flexbox, .grid { border: 2px solid skyblue; border-radius: 10px; padding: 10px; margin-top: 20px; min-height: 150px; } .flexbox ul { padding: 0; display: flex; justify-content: space-around; } .flexbox li { list-style: none; height: 160px; width: 160px; margin: 10px; background: turquoise; display: flex; justify-content: center; align-items: center; } /* GRID */ .grid-container { display: grid; /* séparatuion de la grille en deux(à ses deux enfants), avec à gauche 30% pour l'image et à droite 70% pour le formulaire*/ grid-template-columns: 30% 70%; } /* sizing de l'image css-logo contenu dans la classe grid qui est dans le parent grid-container*/ .grid img { /* l'image remplt 80% de part de grille*/ width: 80%; margin: 20px auto; display: block; } form { display: grid; /* deux colonnes de chacune 1 fraction*/ grid-template-columns: 1fr 1fr; /* trois rangés de chacune 1 fraction*/ grid-template-rows: 1fr 1fr 1fr; /* structuration sous forme de template de notre repartition des composants enfants de la forme*/ grid-template-areas: "i1 i2"/* i1: input1, i2:input2*/ "ta ta"/*ta: text area */ "vi bt"/*vi:, bt: bouton */; } /* on donne du style sur deux éléments en meme temps en les listant avant les parentheses*/ input, textarea { margin: 5px; border: 1px solid darkblue; padding: 10px; font-size: 1.1rem; font-family: "DMSerif"; border-radius: 5px; } /* donner du style uniquement la textearea*/ textarea { /* renseigner le nommage pour le grid template area*/ grid-area: ta; height: 40px; /* empeche le cassage du style de la page en empechant le resizing de la textarea du formulaire*/ resize: none; } /* pour pointer un id d'élément html on utilise la notation préfixe # */ #btn-submit { /* renseigner le nommage*/ grid-area: bt; /* change le le symbole de curseur souris quand il survole sur le bouton*/ cursor: pointer; background: cyan; transition: 0.2s; } /* au survole(hover) de la souris le bouton change de comportement*/ #btn-submit:hover { background: darkblue; /* couleur de text du bouton devient blanc*/ color: white; }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Cours CSS</title> <link rel="stylesheet" href="style.css" /> </head> <body> <header> <h1>Les bases de CSS</h1> </header> <main> <div class="flexbox"> <h2>Flexbox</h2> <ul> <li>boite 1</li> <li>boite 2</li> <li>boite 3</li> </ul> </div> <div class="grid"> <h2>Grid</h2> <div class="grid-container"> <img src="./assets/img/css-logo.png" alt="logo css" /> <form action=""> <input type="text" id="firstname" placeholder="Prénom" /> <input type="text" id="surname" placeholder="Nom" /> <textarea cols="30" rows="10" placeholder="Ici votre message"></textarea> <input type="submit" value="Valider" id="btn-submit" /> </form> </div> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_début"><span class="underline">CSS 시작</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_abs_pos">절대 위치</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } body { font-family: "DMSerif", Verdana; background: url(./assets/img/bg.jpg) center/cover; min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; } main { background: rgba(245, 245, 245, 0.9); min-height: 500px; width: 90%; margin: 0 auto; border: 2px solid rgb(0, 140, 255); border-radius: 20px 20px 0 0; box-shadow: 0px 0px 20px 4px #81cfc6; padding: 15px; } h2 { margin: 0; } .flexbox, .grid, .absolute { border: 2px solid skyblue; border-radius: 10px; padding: 10px; margin-top: 20px; min-height: 150px; } .flexbox ul { padding: 0; display: flex; justify-content: space-around; } .flexbox li { list-style: none; height: 160px; width: 160px; margin: 10px; background: turquoise; display: flex; justify-content: center; align-items: center; } .grid-container { display: grid; grid-template-columns: 30% 70%; } .grid img { width: 80%; margin: 20px auto; display: block; } form { display: grid; grid-template-columns: 1fr 1fr; grid-template-rows: 1fr 1fr 1fr; grid-template-areas: "i1 i2" "ta ta" "vi bt"; } input, textarea { margin: 5px; border: 1px solid darkblue; padding: 10px; font-size: 1.1rem; font-family: "DMSerif"; border-radius: 5px; } textarea { grid-area: ta; height: 40px; resize: none; } #btn-submit { grid-area: bt; cursor: pointer; background: cyan; transition: 0.2s; } #btn-submit:hover { background: darkblue; color: white; } /* ABSOLUTE */ /* Sans élément en Relative, de base, l'élément en absolute l'est par rapport au Body */ /* Il faut mettre une position relative au parent pour contraindre l'élément en absolute dans ses frontières */ .absolute { /* position relative par rapport à son parent, donc contenu dans les frontieres de son parents*/ position: relative; } #circle1 { height: 80px; width: 80px; background: skyblue; position: absolute; border-radius: 150px; top: -20px; right: -20px; } #circle2 { height: 40px; width: 40px; border-radius: 150px; background: teal; position: absolute; left: 50%; transform: /*traslate de 50% de la taille du cercle, pour etre centré par rapport au centre du cercle, plutot que sur son bord gauche par défaut.*/ translateX(-50%); top: 100px; }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Cours CSS</title> <link rel="stylesheet" href="style.css" /> </head> <body> <header> <h1>Les bases de CSS</h1> </header> <main> <div class="flexbox"> <h2>Flexbox</h2> <ul> <li>boite 1</li> <li>boite 2</li> <li>boite 3</li> </ul> </div> <div class="grid"> <h2>Grid</h2> <div class="grid-container"> <img src="./assets/img/css-logo.png" alt="logo css" /> <form action=""> <input type="text" id="firstname" placeholder="Prénom" /> <input type="text" id="surname" placeholder="Nom" /> <textarea cols="30" rows="10" placeholder="Ici votre message"></textarea> <input type="submit" value="Valider" id="btn-submit" /> </form> </div> </div> <div class="absolute"> <h2>Absolute</h2> <span id="circle1"></span> <span id="circle2"></span> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_시작">[toc_시작]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_responsive">반응형</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } body { font-family: "DMSerif", Verdana; background: url(./assets/img/bg.jpg) center/cover; min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; /* pour etre plus responsive on peut passer la taille en vw(view port width) pour qu'elle s'adapte à la taille de l'ecran*/ font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; } main { background: rgba(245, 245, 245, 0.9); min-height: 500px; width: 90%; margin: 0 auto; border: 2px solid rgb(0, 140, 255); border-radius: 20px 20px 0 0; box-shadow: 0px 0px 20px 4px #81cfc6; padding: 15px; } h2 { margin: 0; } .flexbox, .grid, .absolute { border: 2px solid skyblue; border-radius: 10px; padding: 10px; margin-top: 20px; min-height: 150px; } .flexbox ul { padding: 0; display: flex; justify-content: space-around; } .flexbox li { list-style: none; height: 160px; width: 160px; margin: 10px; background: turquoise; display: flex; justify-content: center; align-items: center; } .grid-container { display: grid; grid-template-columns: 30% 70%; } .grid img { width: 80%; margin: 20px auto; /* permet en media query de la centrer en petit écran*/ display: block; } form { display: grid; grid-template-columns: 1fr 1fr; grid-template-rows: 1fr 1fr 1fr; grid-template-areas: "i1 i2" "ta ta" "vi bt"; } input, textarea { margin: 5px; border: 1px solid darkblue; padding: 10px; font-size: 1.1rem; font-family: "DMSerif"; border-radius: 5px; } textarea { grid-area: ta; height: 40px; resize: none; } #btn-submit { grid-area: bt; cursor: pointer; background: cyan; transition: 0.2s; } #btn-submit:hover { background: darkblue; color: white; } .absolute { position: relative; } #circle1 { height: 80px; width: 80px; background: skyblue; position: absolute; border-radius: 150px; top: -20px; right: -20px; } #circle2 { height: 40px; width: 40px; border-radius: 150px; background: teal; position: absolute; left: 50%; transform: translateX(-50%); top: 100px; } /* RESPONSIVE: a partir des tailles d'ecran permet de surcharger les reglages definis plus haut */ @media screen and (max-width: 900px) { .grid-container { display: block; } .grid-container img { width: 40%; } } @media screen and (max-width: 610px) { .flexbox ul { flex-direction: column; align-items: center; } form { grid-template-columns: 1fr; grid-template-rows: 1fr; grid-template-areas: "i1" "i2" "ta" "bt"; } input, textarea { font-size: 0.8rem; } }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Cours CSS</title> <link rel="stylesheet" href="style.css" /> </head> <body> <header> <h1>Les bases de CSS</h1> </header> <main> <div class="flexbox"> <h2>Flexbox</h2> <ul> <li>boite 1</li> <li>boite 2</li> <li>boite 3</li> </ul> </div> <div class="grid"> <h2>Grid</h2> <div class="grid-container"> <img src="./assets/img/css-logo.png" alt="logo css" /> <form action=""> <input type="text" id="firstname" placeholder="Prénom" /> <input type="text" id="surname" placeholder="Nom" /> <textarea cols="30" rows="10" placeholder="Ici votre message"></textarea> <input type="submit" value="Valider" id="btn-submit" /> </form> </div> </div> <div class="absolute"> <h2>Absolute</h2> <span id="circle1"></span> <span id="circle2"></span> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_시작">[toc_시작]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_conclusion">디버그 & 결론</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">/* all elements: supprime les comportements par défaut*/ * { /* les marges à zéro*/ margin: 0; /* les parge internes(padding) à zéro*/ padding: 0; /* tous les bords avec un cadre rouge de 2px. qui est ou et qui fait quoi...*/ border: 2px solid red; }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_시작">[toc_시작]</a></p> </div> </div> </div> https://cheroliv.com/blog/2023/0061_memo_html_post.html Sun, 13 Aug 2023 00:00:00 +0000 blog/2023/0061_memo_html_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_bon_liens">Bon liens</a></li> <li><a href="#_répository_et_code_sample">Répository et code sample</a></li> </ul> </div> <div class="sect1"> <h2 id="_bon_liens">Bon liens</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">html</div> <ul> <li> <p><a href="https://htmlcheatsheet.com" target="_blank" rel="noopener">htmlcheatsheet.com</a>: HTML Cheatsheet</p> </li> </ul> </div> <div class="ulist"> <div class="title">font</div> <ul> <li> <p><a href="https://fontawesome.com" target="_blank" rel="noopener">fontawesome.com</a>: bibliothèque d’icones</p> </li> <li> <p><a href="https://www.toptal.com/designers/htmlarrows/symbols/" target="_blank" rel="noopener">toptal.com/designers/htmlarrows/symbols</a>: Icones natives en HTML</p> </li> </ul> </div> <div class="ulist"> <div class="title">caractères spéciaux et échappements</div> <ul> <li> <p><a href="https://www.sonarsource.com/blog/encoding-differentials-why-charset-matters/" class="bare">https://www.sonarsource.com/blog/encoding-differentials-why-charset-matters/</a></p> </li> <li> <p><a href="https://stackoverflow.com/a/3614344/13104550" class="bare">https://stackoverflow.com/a/3614344/13104550</a></p> </li> <li> <p><a href="https://html.spec.whatwg.org/multipage/named-characters.html" class="bare">https://html.spec.whatwg.org/multipage/named-characters.html</a></p> </li> </ul> </div> <div class="paragraph"> <p><a href="#toc">[toc]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="_répository_et_code_sample">Répository et code sample</h2> <div class="sectionbody"> <div class="paragraph"> <p>github repository: <a href="https://github.com/cheroliv/html-codebase" target="_blank" rel="noopener">html-codebase</a></p> </div> <div class="paragraph"> <p>memo source:<br> index.html</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <!-- Le titre de la page --> <title>Cours HTML</title> <!-- Icone de l'onglet --> <link rel="shortcut icon" href="html-logo.png" /> <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.8.2/css/all.css" /> </head> <body> <header> <h1>Texte - Titre H1</h1> <p> <em>em pour mettre en italique</em>, <strong>strong pour mettre en gras</strong> <span>L'élement en span ne revient pas à la ligne</span>. </p> <p> Lorem ipsum dolor sit amet consectetur adipisicing elit. Exercitationem cumque ratione veniam officiis nulla a debitis at facilis sed dignissimos. </p> </header> <section> <div> <h2>Photo - Titre H2</h2> <img src="./img-1.jpg" alt="image-arbre" height="200" /> </div> <div> <h3>Liste - Titre H3</h3> <ul> <li>UL = unordered list</li> <li>UL = unordered list</li> <li>UL = unordered list</li> </ul> <ol> <li>OL = ordered list</li> <li>OL = ordered list</li> <li>OL = ordered list</li> </ol> </div> <div> <h4>Tableaux - Titre H4</h4> <table border="4" cellpadding="10" cellspacing="4" style="text-align: center"> <thead> <tr> <th>Col 1</th> <th>Col 2</th> <th>Col 3</th> </tr> </thead> <tbody> <tr> <td rowspan="2">Row 1 Cell 1</td> <td>Row 1 Cell 2</td> <td>Row 1 Cell 3</td> </tr> <tr> <td>Row 2 Cell 2</td> <td>Row 2 Cell 3</td> </tr> <tr> <td colspan="3">Row 3 Cell 1</td> </tr> </tbody> </table> </div> <div> <h5><span>♖</span> Liens - Titre H5</h5> <a href="https://htmlcheatsheet.com/" target="_blank">HTML Cheatsheet</a> <br /> <a href="https://www.toptal.com/designers/htmlarrows/symbols/" target="_blank">Icones natifs en HTML</a> </div> <div> <h6><i class="fas fa-video"></i> Vidéo - Titre H6</h6> <video src="video.mp4" height="150" autoplay loop muted></video> </div> </section> <br /> <!-- Formulaires en HTML --> <section> <h2>Formulaire</h2> <form action="/action.php" method="post"> <label for="name">Nom</label> <input id="name" type="text" placeholder="Entrez votre nom" /><br /> <label for="number">Entrez votre age</label> <input type="number" id="number-age" value="15" oninput="document.getElementById('range-age').value=this.value"> <input type="range" id="range-age" min="0" max="100" oninput="document.getElementById('number-age').value=this.value"><br /> <!-- Input select --> <label for="gender">Genre</label> <select id="gender"> <option selected="selected" value="Homme">Homme</option> <option value="Femme">Femme</option> </select><br /> <!-- Input radio --> <div> <input type="radio" name="type" id="human" checked /> <label for="human">Humain</label> <input type="radio" name="type" id="dog" /> <label for="dog">Chien</label> <input type="radio" name="type" id="cat" /> <label for="cat">Chat</label> </div> <textarea cols="20" rows="5" placeholder="Votre message..."></textarea><br /> <!-- Input Checkbox --> <label><input type="checkbox" />Accepter les CGV</label> <br /> <input type="submit" value="Submit" /> </form> </section> <br /> <!-- Mail & envoi de fichiers --> <footer> <a href="mailto:fs@gmail.com">Ecrivez-moi !</a> <br /> <a href="notice.txt" download="nom-du-fichier">Télécharger la notice</a> <details> <summary>Plus d'infos</summary> <p> Lorem ipsum dolor, sit amet consectetur adipisicing elit. Harum, repellendus. </p> </details> </footer> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">[toc]</a></p> </div> </div> </div> https://cheroliv.com/blog/2023/0060_memo_js_post.html Fri, 4 Aug 2023 00:00:00 +0000 blog/2023/0060_memo_js_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>github repository: <a href="https://github.com/cheroliv/js-codebase" target="_blank" rel="noopener">js-codebase</a></p> </div> </div> </div> <div class="sect1"> <h2 id="toc_js"><span class="underline">Intro Javascript</span></h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#start">Variables, opérateurs arithmétiques et chaines de caractères</a></p> </li> <li> <p><a href="#arrays">Les arrays</a></p> </li> <li> <p><a href="#functions">Les fonctions</a></p> </li> <li> <p><a href="#param_x_scope">Paramètres et scopes</a></p> </li> <li> <p><a href="#objects">Les objects</a></p> </li> <li> <p><a href="#loops">Les boucles</a></p> </li> <li> <p><a href="#const_var_let">Const, var et let</a></p> </li> <li> <p><a href="#rest_and_spread_operators">Rest et spread operators</a></p> </li> <li> <p><a href="#destructuring">Destructuring</a></p> </li> <li> <p><a href="#import_export">Import et export de modules</a></p> </li> <li> <p><a href="#classes">Utilisation des classes</a></p> </li> </ol> </div> <div class="paragraph"> <p>index.html</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8"> <title>Document</title> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta http-equiv="X-UA-Compatible" content="ie=edge" /> </head> <body> index <script src="01_start.js"></script> <script src="02_arrays.js"></script> <script src="03_functions.js"></script> <script src="04_param_x_scope.js"></script> <script src="05_objects.js"></script> <script src="06_loops.js"></script> <script src="07_const_var_let.js"></script> <script src="08_rest_and_spread_operators.js"></script> <script src="09_destructuring.js"></script> <script src="10_module_import_export.js"></script> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Intro Javascript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="start">Variables, opérateurs arithmétiques et chaines de caractères</h2> <div class="sectionbody"> <div class="paragraph"> <p>01_start.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">/** * Variables */ //une variable stupide var my_variable = "dummy variable"; console.log(my_variable); //assertion console.assert(my_variable === "dummy variable"); var username = "cheroliv"; console.log(username); console.assert(username === "cheroliv"); //concaténation de string console.assert(username === "cher" + "oliv"); /** * Opérateur arithmétique: + - * / % */ //integer var x = 10; var y = 5; var z = 20; console.log(x + y); console.assert(x + y === 15); console.log(x + y - z); console.assert(x + y - z === -5); console.log(x - y); console.assert(x - y === 5); console.log(x * y); console.assert(x * y === 50); console.log(x / y); console.assert(x / y === 2); console.log("---------"); x = 20; y = 10; console.log(x + y); console.assert(x + y === 30); console.log(x + y - z); console.assert(x + y - z === 10); console.log(x - y); console.assert(x - y === 10); console.log(x * y); console.assert(x * y === 200); console.log(x / z); console.assert(x / z === 1); //Littéraux de gabarits pour string avec backstick ` //Template literals (Template strings) console.assert(`typeof z: ${typeof z}` === "typeof z: number"); console.log(`x is type of : ${typeof x}`); console.log(`y is type of : ${typeof y}`); console.log(`z is type of : ${typeof z}`); //typeof: donne le type de la variable console.assert(typeof x === "number"); console.assert(typeof y === "number"); console.assert(typeof z === "number"); console.log("---------"); /** * Incrémenation/décrémentation */ //incrémantation/décrémentation préfixe console.log(++x) //incrémenté puis affiché: 21 console.log(x) //la valeur incrémenté: 21 //incrémantation/décrémentation suffixe console.log(y++) //affiche la valeur sans incrémenation puis incrémente: 10 console.log(y) //la valeur incrémenté: 11 //décrémentation x--; y--; console.assert(x === 20); console.assert(y === 10); /** * String: chaine de caractères */ console.log(`username: ${username}`); //taille de la string console.log(`username.length: ${username.length}`); console.assert(username.length === 8); console.assert(username.length === "cheroliv".length); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Intro Javascript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="arrays">Les arrays</h2> <div class="sectionbody"> <div class="paragraph"> <p>02_arrays.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">/** * Les arrays */ // auteurs [["nom ", "prénom", "pays"]] var writers = [ ["Karl", "Marx", "de"], ["Jean-Jacques", "Rousseau", "fr"], ["Victor", "Hugo", "fr"], ["René", "Descartes", "fr"], ["Paul", "Verlaine", "fr"], ["Antonio", "Gramsci", "it"], ["Georg", "Lukacs", "hu"], ["Franz", "Kafka", "hu"], ["Arthur", "Rimbaud", "fr"], ["Gérard", "de Nerval", "fr"], ["Chrétien", "de Troyes", "fr"], ["François", "Rabelais", "fr"], ["Georg", "Hegel", "de"], ["Friedrich", "Engels", "de"], ] console.table(writers); // accés aux élèments du tableau console.log(writers[0]); console.log(`${writers[0][0]}, ${writers[0][1]} (${writers[0][2]})`); console.assert("Karl, Marx (de)" === `${writers[0][0]}, ${writers[0][1]} (${writers[0][2]})`); //sauvegarder la valeur du prénom de Marx var karl = writers[0][0] //éditer un élement du tableau, le prénom de Marx writers[0][0] = "Karlito" console.log(`${writers[0][0]}, ${writers[0][1]} (${writers[0][2]})`); console.assert("Karlito, Marx (de)" === `${writers[0][0]}, ${writers[0][1]} (${writers[0][2]})`); console.assert("Karl" === karl); //remettre la valeur initale du prénom de Marx writers[0][0] = karl; console.assert(`${karl}, Marx (de)` === `${writers[0][0]}, ${writers[0][1]} (${writers[0][2]})`); console.log("---------"); /** * Arrays: map/forEach/pop/push/slice/sort/shift/unshift */ var numbers = [1, 5, 4, 3, 2]; console.log("Iterate with forEach"); // parcourir avec array.forEach numbers.forEach((it) => console.log(it)); console.log("---------"); console.log("Iterate with map"); // parcourir avec array.map numbers.map((it) => console.log(it)); console.log("---------"); //afficher les éléments sur une ligne //génère la string avec le formatage des nombres const numbersString = (numberArray) => { var consoleOutput = new String(); numberArray.forEach(number => consoleOutput += `${number}, `); return consoleOutput = consoleOutput.substring(0, consoleOutput.length - 2); }; //affiche la chaine entre crochets dans la console const displayNumbers = (numbersStr) => { console.log(`[${numbersString(numbersStr)}]`); }; console.log("orginal number array") displayNumbers(numbers); console.log("---------"); //push: ajoute à la fin console.log("push"); numbers.push(6); displayNumbers(numbers); console.log("---------"); //pop: suprime le dernier console.log("pop"); numbers.pop(); displayNumbers(numbers); console.log("---------"); //unshift: ajouter le parametre au debut de l'array console.log("unshift"); numbers.unshift(0); displayNumbers(numbers); console.log("---------"); //shift: supprime le premier element de l'array console.log("shift"); numbers.shift(); displayNumbers(numbers); console.log("---------"); //slice: renvoi l'array entre les positions en argument console.log("slice"); var sliceNumbersResult = numbers.slice(2, 4); displayNumbers(sliceNumbersResult); console.log("---------"); //sort asc console.log("sort asc"); var ascSort = numbers.sort((a, b) => a - b); displayNumbers(ascSort); console.log("---------"); //sort desc console.log("sort desc"); var descSort = numbers.sort((a, b) => b - a); displayNumbers(descSort); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Intro Javascript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="functions">Les fonctions</h2> <div class="sectionbody"> <div class="paragraph"> <p>03_functions.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">/** * Les fonctions */ //function style legacy function sayHelloWorldLegacy() { console.log("Hello world legacy!"); } sayHelloWorldLegacy(); function sayHelloLegacy(firstName, lastName, style) { console.log(`Hello ${firstName}, ${lastName} (${style})`); } sayHelloLegacy("Cher", "Oliv", "legacy"); console.log("---------"); //function style arrow const sayHelloWorld = () => console.log("Hello world!"); sayHelloWorld(); const sayHello = (firstName, lastName) => console.log(`Hello ${firstName}, ${lastName}`); sayHello("Cher", "Oliv"); console.log("---------"); var authors = [ ["Chrétien", "de Troyes", "fr"], ["François", "Rabelais", "fr"], ["René", "Descartes", "fr"], ["Jean-Jacques", "Rousseau", "fr"], ["Georg", "Hegel", "de"], ["Karl", "Marx", "de"], ["Friedrich", "Engels", "de"], ["Victor", "Hugo", "fr"], ["Paul", "Verlaine", "fr"], ["Antonio", "Gramsci", "it"], ["Georg", "Lukacs", "hu"], ["Franz", "Kafka", "hu"], ["Arthur", "Rimbaud", "fr"], ["Gérard", "de Nerval", "fr"], ] const displayAuthors = (authorsArray) => authorsArray.forEach(author => console.log(`${author[0]} ${author[1]}, (${author[2]})`) ); displayAuthors(authors); console.log("---------"); /** * valeur par défaut des parametres d'une fonctions */ const add = (a = 0, b = 0) => a + b; console.assert(add() === 0) console.assert(add(1) === 1) console.assert(add(1, 1) === 2) console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Intro Javascript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="param_x_scope">Paramètres et scopes</h2> <div class="sectionbody"> <div class="paragraph"> <p>04_param_x_scope.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">//global scope: visible partout, dans et hors functions var global; const foo = () => { //local scope: visible uniquement dans la fonction foo var bar = "bar" console.log(bar) } foo(); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Intro Javascript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="objects">Les objects</h2> <div class="sectionbody"> <div class="paragraph"> <p>05_objects.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">/** * Les objects */ var authors = [ ["Chrétien", "de Troyes", "fr"], ["François", "Rabelais", "fr"], ["René", "Descartes", "fr"], ["Jean-Jacques", "Rousseau", "fr"], ["Georg", "Hegel", "de"], ["Karl", "Marx", "de"], ["Friedrich", "Engels", "de"], ["Victor", "Hugo", "fr"], ["Paul", "Verlaine", "fr"], ["Antonio", "Gramsci", "it"], ["Georg", "Lukacs", "hu"], ["Franz", "Kafka", "hu"], ["Arthur", "Rimbaud", "fr"], ["Gérard", "de Nerval", "fr"], ]; var hugo = { firstName: authors[7][0], lastName: authors[7][1], country: authors[7][2], }; var book = { author: hugo, title: "Les misérables" }; console.log(hugo); console.log(book); //accéder à un membre de l'objet par point console.log(hugo.country); //accéder à un membre de l'objet par crochet console.log(book["title"]); console.log(book.author.lastName); console.log(book["author"]["firstName"]); //ajouter une clé a un objet hugo.gender = "non binary"; console.assert(hugo.gender === "non binary"); //mettre à jour une clé hugo.gender = "male"; console.assert(hugo.gender !== "non binary"); console.assert(hugo["gender"] === "male"); //supprimer une clé delete hugo.gender; //verfier que l'objet ne contient pas la clé gender console.assert(!Object.keys(hugo).includes("gender")); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Intro Javascript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="loops">Les boucles</h2> <div class="sectionbody"> <div class="paragraph"> <p>06_loops.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">/** * Les boucles: Itérer sur arrays et objets. */ console.log("for loop over array"); var numbers = [12, 10, 8, 6, 4, 2, 0]; for (number of numbers) { console.log(number); } console.log("---------"); console.log("for loop over object key"); var obj = { a: 1, b: 2, c: 3, d: 4 }; for (key in obj) { console.log(key); } console.log("---------"); console.log("for loop over object value"); for (value in obj) { console.log(obj[value]); } console.log("---------"); console.log("another for loop over authors array") var authors = [ ["Chrétien", "de Troyes", "fr"], ["François", "Rabelais", "fr"], ["René", "Descartes", "fr"], ["Jean-Jacques", "Rousseau", "fr"], ["Georg", "Hegel", "de"], ["Karl", "Marx", "de"], ["Friedrich", "Engels", "de"], ["Victor", "Hugo", "fr"], ["Paul", "Verlaine", "fr"], ["Antonio", "Gramsci", "it"], ["Georg", "Lukacs", "hu"], ["Franz", "Kafka", "hu"], ["Arthur", "Rimbaud", "fr"], ["Gérard", "de Nerval", "fr"], ]; for (const [i, value] of authors.entries()) { console.log(`${value[0]}, ${value[1]} (${value[2]})`); } console.log("---------"); console.log("while loop over array") var i = 0 while (i < authors.length) { console.log(`${authors[i][0]}, ${authors[i][1]} (${authors[i][2]})`); i++; } console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Intro Javascript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="const_var_let">Const, var et let</h2> <div class="sectionbody"> <div class="paragraph"> <p>07_const_var_let.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">/** * const X var X let */ //var x du if n'est pas confiné au scope du if const varTest = () => { var x = 1; console.log(x); console.assert(x === 1); if (true) { var x = 2; console.log(x); console.assert(x === 2); } console.log(x); console.assert(x !== 1); console.assert(x === 2); } varTest(); console.log("---------"); //var x est global à tous les fichier js //chargés dans la page html //var x issue du fichier 1_start.js //ligne 46 console.log(x); console.assert(x === 20); console.log("---------"); //premier let x est confiné au scope de la fonction //le let x du if est confiné au scope du if const letTest = () => { let x = 1; console.log(x); console.assert(x === 1); if (true) { let x = 2; console.log(x); console.assert(x === 2); } console.log(x); console.assert(x === 1); console.assert(x !== 2); } letTest(); console.log("---------"); /** * const: déclare un emplacement mémoire non réattribuable * c'est modifiable pour un array, * mais non réinitialisable; * ex: * const arr = [25, 27, 29] * arr = [5, 7] //impossible * arr[0]=20 // possible * ex: * const n = 1; * n = 3; //impossible */ const arr = [25, 27, 29] console.table(arr); arr[0] = 20 // possible console.table(arr); arr.pop() console.table(arr); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Intro Javascript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="rest_and_spread_operators">Rest et spread operators</h2> <div class="sectionbody"> <div class="paragraph"> <p>08_rest_and_spread_operators.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">/** * Opérateur de rest: * const add = (...operandes) => a + b; * ou avec parametres avec valeur par défaut * const add = (a=0, b=0, ...operandes) => a + b; */ /** * spread opérateur: * récupère l'ensemble des elements d'une collection, * dans un array */ const user_ages = [25, 56, 12, 58, 41, 62, 26]; const max_user_age = Math.max(...user_ages); const min_user_age = Math.min(...user_ages); console.assert(max_user_age == 62); console.assert(min_user_age == 12); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Intro Javascript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="destructuring">Destructuring</h2> <div class="sectionbody"> <div class="paragraph"> <p>09_destructuring.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">/** * L'affectation par décomposition (destructuring) */ const user = { first_name: "Oliv", last_name: "Cher", nick_name: "cheroliv", gender: "male", is_adult: true }; console.log(user); //première façon d'initaliser des variables sans destructuration let first_name_legacy = user.first_name; let last_name_legacy = user.last_name; let nick_name_legacy = user.nick_name; let gender_legacy = user.gender; let is_adult_legacy = user.is_adult; console.assert("Oliv" === first_name_legacy); console.assert("Cher" === last_name_legacy); console.assert("cheroliv" === nick_name_legacy); console.assert("male" === gender_legacy); console.assert(true === is_adult_legacy); console.log("---------"); /** * Initialisation par déstructuration */ const { first_name, last_name, nick_name, gender, is_adult } = user; console.assert(user.first_name === first_name); console.assert(user.last_name === last_name); console.assert(user.nick_name === nick_name); console.assert(user.gender === gender); console.assert(user.is_adult === is_adult); /** * Intialisation par déstructuration des arrays */ //cible explicite const [a1, a2] = [15, 25, 17, 81, 51, 46]; console.assert(a1 === 15); console.assert(a2 === 25); //cible avec position par rapport aux index par virgules //je veux b3 à 46 const [b1, b2, , , , b3] = [15, 25, 17, 81, 51, 46]; console.assert(b1 === 15); console.assert(b2 === 25); console.assert(b3 === 46); //déstructuration avec operateur de rest // je contruit un autre avec avec les elements // à partir du premier élèment non destructuré const [c1, c2, ...sub_arr] = [15, 25, 17, 81, 51, 46]; console.assert(b1 === 15); console.assert(b2 === 25); console.assert(sub_arr.length === 4); console.assert(sub_arr[0] === 17); console.assert(sub_arr[1] === 81); console.assert(sub_arr[2] === 51); console.assert(sub_arr[3] === 46); // Une boucle pour comparer le resultat attendu for (const [i, value] of[15, 25, 17, 81, 51, 46].entries()) { //on reconstruit le tableau à chaque iteration console.assert([c1, c2].concat(sub_arr)[i] === value); }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Intro Javascript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="import_export">Import et export de modules</h2> <div class="sectionbody"> <div class="paragraph"> <p>10_module_import_export.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">/** * Import et export de module * * Dans le fichier html * au niveau de la balise d'import de script * spécifier le type module * * 1er technique: import nommé des fonctions: * import { sum, minus, times, div, rem } from "./dummy_math_functions.js"; * * 2eme technique: import global des fonction avec l'asterisque(*) * en préfixant l'import par un nommage du fichier importé: * import * as math from "./dummy_math_functions.js"; * * 3eme technique: import par alias avec le mot clé "as" * import { * sum as add, * minus as substract, * times as multiply, * div as divide, * rem as modulo * } from "./dummy_math_functions.js"; */ import { sum, minus, times, div, rem } from "./dummy_math_functions.js"; console.assert(sum(1, 1) === 2); console.assert(minus(4, 2) === 2); console.assert(times(2, 2) === 4); console.assert(div(4, 2) === 2); console.assert(rem(4, 2) === 0);</code></pre> </div> </div> <div class="paragraph"> <p>dummy_math_functions.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">//sum const sum = (x, y) => x + y; // subtraction const minus = (x, y) => x - y; // multiplication const times = (x, y) => x * y; // division const div = (x, y) => x / y; // remainder: reste de la division euclidiene const rem = (x, y) => x % y; // log sum const sum_log = (x, y) => console.log(sum(x, y)); // log subtraction const minus_log = (x, y) => console.log(minus(x, y)); // log multiplication const times_log = (x, y) => console.log(times(x, y)); // log division const div_log = (x, y) => console.log(div(x, y)); // log remainder const rem_log = (x, y) => console.log(rem(x, y)); export { sum, minus, times, div, rem, sum_log, minus_log, times_log, div_log, rem_log };</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Intro Javascript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="classes">Utilisation des classes</h2> <div class="sectionbody"> <div class="paragraph"> <p>11_classes.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">/** * Utilisation des classes */ //creation d'un objet class Account { constructor(username) { this.username = username; } }; const acc1 = new Account("cheroliv"); console.table(acc1); console.assert(acc1.username === "cheroliv"); console.log("---------"); //création d'un objet et ajout de getter et setter(accesseurs) class AccountInfo { constructor(username) { this._username = username; } get username() { return this._username; } /** * @param {(arg0: string) => void} new_username */ set new_username(new_username) { this._username = new_username; } }; const acc_info1 = new AccountInfo("cheroliv"); console.table(acc_info1); //accés au membre _username avec le getter username() console.assert(acc_info1.username === "cheroliv"); //update la valeur username de acc_info1 avec le setter acc_info1.new_username = "imrandeh"; console.assert(acc_info1.username === "imrandeh"); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Intro Javascript</span></a></p> </div> </div> </div> https://cheroliv.com/blog/2022/0054_memo_cadrage_post.html Sat, 31 Dec 2022 00:00:00 +0000 blog/2022/0054_memo_cadrage_post.html <div class="sect1"> <h2 id="_구도">구도</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_워크숍_1_비전">워크숍 1 : 비전</h3> <div class="sect3"> <h4 id="_1_패턴_qqoqcp_누구_무엇_어디_언제_어떻게_왜">1. 패턴 “QQOQCP” – 누구, 무엇, 어디, 언제, 어떻게, 왜</h4> </div> <div class="sect3"> <h4 id="_2_제품_비전_보드">2. 제품 비전 보드</h4> <div class="sect4"> <h5 id="_대상_그룹">대상 그룹</h5> <div class="paragraph"> <p>제품을 사용하거나 서비스를 이용하는 사용자는 누구인가요? (직접, 간접)</p> </div> </div> <div class="sect4"> <h5 id="_필요">필요</h5> <div class="paragraph"> <p>핵심 사용자의 주요 5가지 필요는 무엇인가요?</p> </div> </div> <div class="sect4"> <h5 id="_제품">제품</h5> <div class="paragraph"> <p>내 가치 제안은 무엇인가요? 제품의 5가지 주요 기능은 어떤 것들에 대응하기 위해 제공되나요? 필요</p> </div> </div> <div class="sect4"> <h5 id="_비즈니스_목표">비즈니스 목표</h5> <div class="paragraph"> <p>성공의 기준은 무엇인가요?</p> </div> </div> <div class="sect4"> <h5 id="_비전">비전</h5> <div class="paragraph"> <p>4개의 열이 모두 채워지면, Product Vision의 비전 부분을 채워야 합니다. 보드를 완전한 문장으로</p> </div> </div> </div> </div> <div class="sect2"> <h3 id="_워크숍_2_퍼소나사용자_여정">워크숍 2: 퍼소나/사용자 여정</h3> <div class="ulist"> <div class="title">각 페르소나에 대한 사용자 경로를 정의:</div> <ul> <li> <p>누가 내 서비스를 이용할까요? (대상)</p> </li> <li> <p>그가 뭘 하고 싶어? (하지만)</p> </li> <li> <p>어떻게 할 것인가? (사용자 경로)</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_워크숍_3_영역_정의_스토리보드_사이트맵">워크숍 3: 영역 정의, 스토리보드, 사이트맵</h3> <div class="sect3"> <h4 id="_1_용도_구역">1. 용도 구역</h4> </div> <div class="sect3"> <h4 id="_2_스토리보드">2. 스토리보드</h4> </div> <div class="sect3"> <h4 id="_3_사이트맵">3. 사이트맵</h4> </div> </div> <div class="sect2"> <h3 id="_워크숍_4_와이어프레임무드보드">워크숍 4: 와이어프레임/무드보드</h3> <div class="sect3"> <h4 id="_1_와이어프레임">1. 와이어프레임</h4> </div> <div class="sect3"> <h4 id="_2_무드보드">2. 무드보드</h4> </div> </div> <div class="sect2"> <h3 id="_워크숍_5_스토리_맵핑_사용자_스토리">워크숍 5: 스토리 맵핑/ 사용자 스토리</h3> <div class="sect3"> <h4 id="_스토리_매핑_사용자_스토리_우선순위">스토리 매핑 (사용자 스토리 우선순위)</h4> </div> <div class="sect3"> <h4 id="_type_dutilisateur로서_나는_un_objectif를_원한다_왜냐하면_une_raison_때문이다"><type d’utilisateur>로서, 나는 <un objectif>를 원한다, 왜냐하면 <une raison> 때문이다.</h4> </div> </div> <div class="sect2"> <h3 id="_워크숍_6_백로그">워크숍 6: 백로그</h3> <div class="paragraph"> <p><a href="https://www.atlassian.com/fr/agile/scrum/backlogs">백로그들</a></p> </div> </div> <div class="sect2"> <h3 id="_아뜰리에_7_기술_및_건축">아뜰리에 7: 기술 및 건축</h3> </div> </div> </div> https://cheroliv.com/blog/2022/0053_memo_kotlin_post.html Sun, 29 May 2022 00:00:00 +0000 blog/2022/0053_memo_kotlin_post.html <div class="sect1"> <h2 id="_좋은_링크">좋은 링크</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://play.kotlinlang.org/">코틀린랭 플레이그라운드</a>+</p> </div> <div class="paragraph"> <p><a href="https://arrow-kt.io/">arrow.kt</a>+</p> </div> <div class="paragraph"> <p><a href="https://arkivanov.github.io/MVIKotlin/">MVI:모델 뷰 인텐트</a>+</p> </div> <div class="paragraph"> <p><a href="https://github.com/arkivanov/Essenty">필수적인</a>+</p> </div> <div class="paragraph"> <p><a href="https://arkivanov.github.io/Decompose/">분해하다</a><br></p> </div> </div> </div> <div class="sect1"> <h2 id="_다양한_코드_조각">다양한 코드 조각</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_맵리듀스">맵리듀스</h3> <div class="paragraph"> <p>바이트 리스트를 문자열 리스트로 변환하고 문자열 리스트를 요약합니다.<br> 연결이 포함된 문자열 안 요청(requestBodyContent:byte[])가 전송된 것을 어떻게 로그하나요?</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">log.info( requestBodyContent!!.map { it.toInt().toChar().toString() } .reduce { request: String, s: String -> request + s } )</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_enum_및_sealed_클래스">enum 및 sealed 클래스</h3> <div class="paragraph"> <p>포스트:<a href="0038_training_kotlin_enum_sealed_class_post">교육 코틀린 열거형 밀봉된 클래스</a></p> </div> </div> <div class="sect2"> <h3 id="_함수형_인터페이스와_메서드_참조">함수형 인터페이스와 메서드 참조</h3> <div class="paragraph"> <p>엔티티를 DTO 도메인 모델로 변환하는 참조 메서드(함수형 스타일, Java 8)를 사용할 수 있다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">fun findAllByLoginNot( pageable:Pageable, login:String) :Page<UserDto> { return userDao.findAllByLoginNot( pageable, login).map(::fromEntity) }</code></pre> </div> </div> <div class="paragraph"> <p>하나https://stackoverflow.com/a/22245383/837404[좋은 설명]</p> </div> </div> <div class="sect2"> <h3 id="_표준_출력_캡처">표준 출력 캡처</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">package functional import java.io.ByteArrayOutputStream import java.io.PrintStream import java.lang.System.out import java.lang.System.setOut import kotlin.test.AfterTest import kotlin.test.BeforeTest import kotlin.test.Test import kotlin.test.assertEquals class BasicsHOF { private val standardOut: PrintStream? = out private val outputStreamCaptor = ByteArrayOutputStream() @BeforeTest fun setUp() = setOut(PrintStream(outputStreamCaptor)) @AfterTest fun tearDown() = setOut(standardOut) @Test fun `three times dope`() { 3.times { println("Hello") } assertEquals( buildString { repeat(3) { append("Hello\n") } deleteAt(length - 1) }, outputStreamCaptor .toString() .trim() ) } fun Int.times(fn: () -> Unit) = (1..this).forEach { _ -> fn() } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_kotlin에서_apply_run_let_also_use_with의_차이는_무엇인가요">Kotlin에서 apply, run, let, also, use, with의 차이는 무엇인가요?</h3> <div class="paragraph"> <p><strong>Kotlin 함수 비교 및 람다 형식 사용 참고</strong></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_적용하다">적용하다</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">서론 Kotlin 함수들`apply`, <code>run</code>, <code>let</code>, <code>also</code>, <code>use</code>, et `with`다른 방법으로 객체를 처리할 수 있는 방법을 제공합니다. 각각은 자체 사용 사례와 동작을 가집니다. 게다가, 람다 참조 형태는 기존 람다 함수를 참조함으로써 코드를 더 가독성 있고 재사용 가능하게 만들 수 있습니다.</div> <p>함수`apply`생성 중에 객체를 구성하는 데 사용됩니다. 호출된 객체를 반환합니다.</p> </div> <div class="paragraph"> <p>람다 참조 예시 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val someObject = SomeClass().apply(::configureObject)</code></pre> </div> </div> <div class="paragraph"> <p>람다를 사용한 예시 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val someObject = SomeClass().apply { // configuration des propriétés de someObject }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_run">run</h2> <div class="sectionbody"> <div class="paragraph"> <p>함수`run`객체에서 코드 블록을 실행하여 그 결과를 반환하는 데 사용됩니다.</p> </div> <div class="paragraph"> <p>람다 참조 예시 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val result = someObject.run(::someFunction)</code></pre> </div> </div> <div class="paragraph"> <p>예제와 lambda :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val result = someObject.run { // bloc de code à exécuter sur someObject // la dernière expression est renvoyée }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_let">let</h2> <div class="sectionbody"> <div class="paragraph"> <p>함수`let`객체에서 코드 블록을 실행하고 코드 블록의 결과를 반환하는 데 사용됩니다.</p> </div> <div class="paragraph"> <p>예시와 람다 참조 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val result = someObject.let(::processObject)</code></pre> </div> </div> <div class="paragraph"> <p>람다와 함께 예시 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val result = someObject.let { // bloc de code à exécuter sur someObject // la dernière expression est renvoyée }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_또한">또한</h2> <div class="sectionbody"> <div class="paragraph"> <p>함수`also`객체에 추가적인 작업을 수행하고, 호출된 객체를 반환하는 데 사용됩니다.</p> </div> <div class="paragraph"> <p>람다 참조 예시 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">someObject.also(::performAdditionalAction)</code></pre> </div> </div> <div class="paragraph"> <p>람다 예시 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">someObject.also { // action additionnelle sur someObject }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_사용">사용</h2> <div class="sectionbody"> <div class="paragraph"> <p>함수`use`는 사용 후 닫아야 하는 리소스를 다룰 때 사용됩니다. 자동으로 함수를 호출합니다.`close`블록의 끝에.</p> </div> <div class="paragraph"> <p>람다 참조 예시 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">someResource.use(::useResource)</code></pre> </div> </div> <div class="paragraph"> <p>람다와 함께하는 예시 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">someResource.use { // travailler avec la ressource }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_와_함께">와 함께</h2> <div class="sectionbody"> <div class="paragraph"> <p>함수`with`는 여러 메서드를 객체에 대해 호출할 때 이름을 반복하지 않도록 사용되며, 마지막 식의 결과를 반환합니다.</p> </div> <div class="paragraph"> <p>예시와 lambda reference :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val result = with(someObject, ::processWithObject)</code></pre> </div> </div> <div class="paragraph"> <p>람다를 사용한 예시 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val result = with(someObject) { // appeler des méthodes sur someObject // la dernière expression est renvoyée }</code></pre> </div> </div> <div class="paragraph"> <p>람다 참조 형태 또는 블록을 사용해`{}`, 로직을 별도의 함수에 캡슐화할 수 있습니다, 이를 통해 코드의 가독성과 재사용성을 향상시킵니다.</p> </div> </div> </div> <div class="sect1"> <h2 id="_let_function에서_kotlin">let Function에서 Kotlin</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">let이 객체에 적용된 부작용과 함께 객체를 반환하는지, 아니면 입력의 초기 상태 그대로 반환하는지, (let)에 따라 달라지나요 ?</div> <p>함수`let`Kotlin에서 개체에 대한 작업을 수행하고 다른 결과를 반환하는 데 사용됩니다. 그러나 함수에 대해 주목할 중요한 점이 있습니다.`let`호출된 객체의 초기 상태를 수정하지 않습니다.</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>서명</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>inline fun <T, R> T.let(block: (T) → R): R</code></p></td> </tr> </tbody> </table> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>사용</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">함수`let`이는 객체에 변형을 적용하고 그 변형을 기반으로 결과를 얻는 데 일반적으로 사용됩니다.</p></td> </tr> </tbody> </table> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>결과</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">함수에서 반환된 값`let`는 인수로 전달된 lambda 표현식의 결과이며, 일반적으로 객체에서 수행된 작업의 결과입니다.</p></td> </tr> </tbody> </table> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>부작용</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">함수이지만`let`람다 표현식에서 사용될 때 객체에 부작용을 일으킬 수 있지만, 객체의 초기 상태를 수정하지는 않는다.</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>따라서, 함수`let`객체에 대한 작업을 수행하면서 파생된 결과를 얻면서 원래 객체의 무결성을 보존하는 한 가지 우아한 방법이다.</p> </div> </div> </div> https://cheroliv.com/blog/2022/0052_memo_jvm_post.html Sat, 28 May 2022 00:00:00 +0000 blog/2022/0052_memo_jvm_post.html <div class="sect1"> <h2 id="toc">table des matières</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#char">chaines de caractères et caractères</a></p> </li> <li> <p><a href="#math">nombres et math</a></p> </li> <li> <p><a href="#date">dates et heures</a></p> </li> <li> <p><a href="#java8date">dates et heures java8</a></p> </li> <li> <p><a href="#arrCol">tableaux et collections</a></p> </li> <li> <p><a href="#sysProp">System.Properties</a></p> </li> <li> <p><a href="#threads">Threads</a></p> </li> <li> <p><a href="#regex">Expressions Régulières</a></p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="char">chaines de caractères et caractères</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">import java.text.Collator import java.util.* import kotlin.test.* class StringsTest { @Test fun `chaines de caractères et caractères`() { //inférence de type val s = "C'est" assertEquals("C'est", s) //concaténation val t: String = s + " le moment." assertEquals("C'est le moment.", t) // StringBuilder val t1: String = s + buildString { append(" le moment.") } assertEquals("C'est le moment.", t1) //interpolation val t2 = "$s le moment." assertEquals("C'est le moment.", t2) //multiligne chaine de caractères val t3 = """$s le moment.""" assertEquals("C'est le moment.", t3) //conversion de type val t4 = t + " " + 23.4 assertEquals("C'est le moment. 23.4", t4) val t5 = 'C'.toString() assertEquals("C", t5) //taille de la chaine de caractères assertEquals(16, t.length) //sous-chaine d'une chaine de caractères //retourne une chaine de caractères contenant, //les caractères aux positions x à y-1 //sub = t.substring(x, y) //t = "C'est le moment." //retourne les caractères 6 et 7 var sub = t.substring(6, 8) assertEquals("le", sub) //retourne les caractères 0 à 4 sub = t.substring(0, 5) assertEquals("C'est", sub) //la longueur d'une sous-chaine est toujours égale (y-x) val numChars = sub.length assertEquals(5 - 0, numChars) //extraction des caractères d'une chaine assertEquals('e', t.elementAt(2)) assertEquals('e', t.get(2)) assertEquals('e', t[2]) //conversion d'une chaine en tableau de caractères val ca = t.toCharArray() assertEquals(t.length, ca.size) t.mapIndexed { index, char -> assertEquals(char, ca[index]) } //place les 4 premiers caractères de t1 //dans le tableau ca a la position 2 (t as java.lang.String).getChars( /* srcBegin = */ 0, /* srcEnd = */ 3, /* dst = */ ca, /* dstBegin = */ 1 ) assertEquals("CC'et le moment.", String(ca)) //colle tous les caractères dans un meme string assertEquals("CC'et le moment.", ca.concatToString()) //to lower case assertEquals("c'est le moment.", t.toLowerCase()) assertEquals("c'est le moment.", t.lowercase()) //to upper case assertEquals("C'EST LE MOMENT.", t.toUpperCase()) assertEquals("C'EST LE MOMENT.", t.uppercase()) //comparaison de chaines de caractères //t = "C'est le moment." assertFalse(t.equals("hello")) assertFalse(t == "hello") //ignore la casse assertTrue(t.equalsIgnoreCase("C'EST LE MOMENT.")) assertTrue(t.equals("C'EST LE MOMENT.", ignoreCase = true)) //démarre par assertTrue(t.startsWith("C'est")) //se finit par assertTrue(t.endsWith("le moment.")) //compareTo //retourne une valeur < 0, car s est //alphabétiquement avant "N'est" val r1: Int = s.compareTo("N'est") assertTrue(r1 < 0) //variante ignorant la casse val r1Prime: Int = (s as java.lang.String).compareToIgnoreCase("n'est") assertTrue(r1Prime < 0) //retourne 0 si les chaines sont equivalente val r2: Int = s.compareTo("C'est") assertEquals(0, r2) //retourne une valeur > 0 car s vient apres "B'est" val r3: Int = s.compareTo("B'est") assertTrue(r3 > 0) //Recherche de caractères et de sous-chaines de caractères //recherche de caractères //position du premier caractères 't' var pos = t.indexOf('t') assertEquals(4, pos) //position du suivant pos = t.indexOf('t', pos + 1) assertEquals(14, pos) //retour d'érreur -1 si absence de suivant pos = t.indexOf('t', pos + 1) assertEquals(-1, pos) //position du dernier 't' dans la chaine: 14 pos = t.lastIndexOf('t') assertEquals(14, pos) //recherche de 't' vers l'arrière a partir du caractères 13 pos = t.lastIndexOf('t', pos - 1) assertEquals(4, pos) //recherche de sous-chaines //retourne 2 pos = t.indexOf("est") assertEquals(2, pos) //"est" n'apparait qu'une seule fois: retourne -1 pos = t.indexOf("est", pos + 1) assertEquals(-1, pos) //recherche d'une sous-chaine depuis l'arrière //t = "C'est le moment." //retourne 6 pos = t.lastIndexOf("le ") assertEquals(6, pos) //extrait depuis la position 9, //renvoi toute la chaine après "le " val noun = t.substring(pos + 3) assertEquals(-1, noun.indexOf("le ")) //remplacement de toutes les instances d'un caractère //par un autre caractère //ne fonctionne que avec les caractères, pas les chaines val exclaim: String = t.replace('.', '!') assertEquals('!', exclaim.get(exclaim.length - 1)) assertEquals(exclaim.length - 1, exclaim.indexOf('!')) assertEquals(-1, exclaim.indexOf('.')) //suppression des espaces blancs //au début et à la fin d'une chaine val noextraspaces = t.trim() assertNotEquals(' ', noextraspaces.get(0)) assertNotEquals(' ', noextraspaces.get(noextraspaces.length - 1)) //extraction des instances uniques de chaines de caractères //avec intern() val s1 = s.intern() assertEquals(s, s1) val s2 = "C'est".intern() assertEquals("C'est", s2) assertEquals(s1, s2) //StringBuilder pour manipuler les caractères d'une chaine de caractères //crée un tampon StringBuilder à partir d'une chaine de caractères val b = StringBuilder("N'est") //extrait et définit des caractères individuel du tampon StringBuilder //le caractères à l'index 0 val c: Char = b.get(0) assertEquals('N', c) //modifier le premier caractère de la chaine b.setCharAt(0, 'C') assertEquals(s, b.toString()) //ajouter des données à un StringBuilder b.append(' ') b.append("le moment.") b.append(23) //insère des chaines de caractères ou autre dans le StringBuilder b.insert(6, "pas ") assertEquals("C'est pas le moment.23", b.toString()) //remplace un sous ensemble de caractères //avec une chaine de caractères donnée b.replace(2, 9, "est") assertEquals("C'est le moment.23", b.toString()) //supprime les caractères b.delete(15, 18) assertEquals("C'est le moment", b.toString()) b.deleteCharAt(2) assertEquals("C'st le moment", b.toString()) //insert à la postion 2 et décale reste à droite(sans perte de données) b.insert(2, 'e') //tronque la taille de la donnée b.setLength(5) assertEquals("C'est", b.toString()) //inverse les caractères de la chaine b.reverse() assertEquals("tse'C", b.toString()) //écrase le StringBuilder, pret à etre réutilisé b.setLength(0) assertEquals("", b.toString()) //java.util.StringTokenizer pour fragmenter une chaine //de caractères en un ensemble de mots var st = StringTokenizer(t) //nb d'items encore présentent dans la file assertEquals(3, st.countTokens()) //est ce que il y a encore des items dans la file assertTrue(st.hasMoreTokens()) //récupérer le token courrant assertEquals("C'est", st.nextToken()) assertEquals("le", st.nextToken()) assertEquals("moment.", st.nextToken()) assertFalse(st.hasMoreTokens()) assertEquals(0, st.countTokens()) //extraire des occurences de mots délimités //par des caractères autres que des expaces. val str = "a:b:c:d" st = StringTokenizer(str, ":") assertEquals(4, st.countTokens()) assertTrue(st.hasMoreTokens()) assertEquals("a", st.nextToken()) assertEquals("b", st.nextToken()) assertEquals("c", st.nextToken()) assertEquals("d", st.nextToken()) assertFalse(st.hasMoreTokens()) assertEquals(0, st.countTokens()) //text="C'est le moment." val text = t.toCharArray() var p = 0 //sauter les espaces de tete //pour ramener p à la position du premier caractère imprimable while ((p < text.size) && (Character.isWhitespace(text[p])) ) p++ assertEquals(0, p) assertEquals("C'est le moment.", text.concatToString()) //met le premier mot du texte en majuscule while (p < text.size && Character.isLetter(text[p])) { text[p] = Character.toUpperCase(text[p]) p++ } assertEquals(1, p) assertEquals('C', text[0]) assertTrue(Character.isUpperCase(text[0])) assertFalse(Character.isLetter(text[1])) //comparer des chaines de caractères // avec les contrainte la locale système val col = Collator.getInstance() //le résulat est négatif car chica //est avant chico dans l'ordre alphabétique assertTrue(col.compare("chica", "chico") < 0) } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">table des matières</a></p> </div> </div> </div> <div class="sect1"> <h2 id="math">nombres et math</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">import java.math.BigInteger import java.security.SecureRandom import java.text.NumberFormat import java.util.* import kotlin.test.* class NumbersMathTest { @Test fun `Nombres et Math`() { //Constantes utiles Byte.MIN_VALUE Byte.MAX_VALUE Short.MIN_VALUE Short.MAX_VALUE Float.MIN_VALUE Float.MAX_VALUE Math.PI Math.E val s = "-42" //conversion de chaine de caractères //vers un nombre, si possible. var b: Byte = java.lang.Byte.parseByte(s) var sh: Short = java.lang.Short.parseShort(s) var i: Int = java.lang.Integer.parseInt(s) var l: Long = java.lang.Long.parseLong(s) var f: Float = java.lang.Float.parseFloat(s) var d: Double = java.lang.Double.parseDouble(s) //valeur exacte val f_exac = java.lang.Float.valueOf(s) val d_exac = java.lang.Double.valueOf(s) //les routines de conversions entière gérent //les nombres dans diverses bases. //1011 en binare est égal a 11 en base dix b = java.lang.Byte.parseByte("1011", 2) assertEquals(11, b) //ff en base 16(hexa) est égal à 255 en base dix. sh = java.lang.Short.parseShort("ff", 16) assertEquals(255, sh) //la méthode valueOf() peut gérer des bases arbitraires. i = java.lang.Integer.valueOf("egg", 17).toInt() assertEquals(4334, i) //la méthode decode() gére les representations octale, //décimal, hexadécimal, en fonction du préfixe numérique //de la chaine de caractères //un 0 de tete signifie base 8 //un 0x de tete signifie base 16 //les autres sont en base 10 val sho = java.lang.Short.decode("0377") //la classe Integer peut convertir les nombres //en diverses chaines de caractères. val decimal = java.lang.Integer.toString(42) assertEquals("42", decimal) val decimal_ = 42.toString() assertEquals("42", decimal_) val binary = java.lang.Integer.toBinaryString(42) assertEquals("101010", binary) val octal = java.lang.Integer.toOctalString(42) assertEquals("52", octal) val hex = java.lang.Integer.toHexString(42) assertEquals("2a", hex) val base36 = java.lang.Integer.toString(42, 36) assertEquals("16", base36) val base36_ = 42.toString(36) assertEquals("16", base36_) //java.text.NumberFormat effectue la conversion // d'une maniere spécifique aux parametres locaux //sans parametre prend la local systeme comme reference val nf = NumberFormat.getNumberInstance(Locale.FRANCE) val formatted_number = nf.format(9876543.21) assertNotEquals("9876543.21", formatted_number) //parse la chaine de caractères en fonction des parametres locaux(fr) val n = nf.parse("1234567,89") assertEquals(1234567.89, n) //les valeurs monétaires sont parfois formaté // d'une maniere differente des nombres val money_format = NumberFormat.getCurrencyInstance(Locale.FRANCE) assertEquals("123,40 €", money_format.format(1234.56)) //java.lang.Math d = Math.toRadians(27.0) d = Math.cos(d) d = Math.sqrt(d) d = Math.log(d) d = Math.exp(d) d = Math.pow(10.0, d) d = Math.atan(d) d = Math.toDegrees(d) //arrondi au dessus val up = Math.ceil(d) //arrondi au dessous val down = Math.floor(d) //arrondi au plus près val nearest = Math.round(d) //java.lang.Math.Random() val r = Math.random() assertTrue(r >= 0.0 && r < 1.0) //créé un nouvel objet Random, en l'initialisant //avec l'heure courante val generator = java.util.Random(System.currentTimeMillis()) //prochaine valeur aléatoire de taille double d = generator.nextDouble() assertTrue((d >= 0.0) && (d < 1.0)) //prochaine valeur aléatoire de taille float f = generator.nextFloat() assertTrue((f >= 0.0) && (f < 1.0)) //prochaine valeur aléatoire de taille long l = generator.nextLong() assertTrue( (Math.abs(l) <= Long.MAX_VALUE) && (Math.abs(l) >= 0) ) //prochaine valeur aléatoire de taille int i = generator.nextInt() assertTrue( (Math.abs(i) <= java.lang.Integer.MAX_VALUE) && (Math.abs(i) >= 0) ) val limit = 100 //prochaine valeur aléatoire de taille int //la limit max du ramdom est ramené à limit //et la limit min est 0 i = generator.nextInt(limit) assertTrue(i in 0 until limit) //prochaine valeur aléatoire de taille booléen val bool = generator.nextBoolean() assertNotNull(bool) //valeur moyenne 0.0, déviation standard 1.0 d = generator.nextGaussian() //randoms bytes //rempli un tableau avec des valeurs byte aléatoires val b_arr = ByteArray(128) generator.nextBytes(b_arr) b_arr.iterator().forEachRemaining { assertTrue( it <= Byte.MAX_VALUE && it >= Byte.MIN_VALUE ) } //java.security.SecureRandom pour les nombres aléatoires //utilisé en cryptographie val secure_generator = SecureRandom() //le générateur génère sa propre tete de liste sur 16 octets secure_generator.setSeed(secure_generator.generateSeed(16)) val sec_b_arr = ByteArray(128) secure_generator.nextBytes(sec_b_arr) sec_b_arr.iterator().forEachRemaining { assertTrue( it <= java.lang.Byte.MAX_VALUE && it >= java.lang.Byte.MIN_VALUE ) } //java.math.BigDecimal java.math.BigInteger //pour travailler sur des grandes valeurs. //calcule de la factorielle de 1000 var total = BigInteger.valueOf(1) (2..1000).forEach { total = total.multiply(BigInteger.valueOf(it.toLong())) } assertTrue(total.toString().length == 2568) } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">table des matières</a></p> </div> </div> </div> <div class="sect1"> <h2 id="date">dates et heures</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">import java.text.DateFormat import java.text.SimpleDateFormat import java.time.Instant import java.util.* import kotlin.test.Test import kotlin.test.assertEquals import kotlin.test.assertTrue class DatesHoursTest { @Test fun `Dates et heures`() { //l'heure courante en millisecondes val t0 = System.currentTimeMillis() //une autre représentation de la meme information val now = java.util.Date() //converti un objet java.util.Date en une valeur long. val t1 = now.getTime() assertTrue(t1 > Instant.EPOCH.toEpochMilli()) //kotlin property access syntaxe style val t1_prime = now.time //java.text.DateFormat //affiche la date d'aujourd'hui en utilisant le format //par défaut des parametres locaux val defaultDateFormat = DateFormat.getDateInstance() //personnalisation du formatage et de la locale val df = DateFormat.getDateInstance(DateFormat.LONG, Locale.FRANCE) val localeFormattedDate = df.format(Date()) //constantes pour les styles de pattern de formatage assertEquals(0, DateFormat.FULL) assertEquals(1, DateFormat.LONG) assertEquals(2, DateFormat.MEDIUM) assertEquals(3, DateFormat.SHORT) assertEquals(2, DateFormat.DEFAULT) //utilise pour l'heure un format abrégé avec //des parametres personnalisés val tf = DateFormat.getTimeInstance( DateFormat.SHORT, Locale.FRANCE ) //affiche l'heure en utilisant le format de tf val shortTime = tf.format(Date()) assertTrue(shortTime.contains(':')) //affiche la date et l'heure en utilisant //un format détaillé val longTimeStamp = DateFormat.getDateTimeInstance( DateFormat.FULL, DateFormat.FULL, ) assert(longTimeStamp.format(Date()).isNotEmpty()) //utilisez java.text.SimpleDateFormat //pour définir votre propre modele de formatage val customFormat = SimpleDateFormat("yyyy.MM.dd") assertEquals(10, customFormat.format(Date()).length) //DateFormat peut également parser les date contenu dans des chaines val kotlinAnnounceDate = customFormat.parse("2019.05.08") //la class Date et sa représentation en millisecondes //n'autorise qu'une forme trés simple d'arithmétique //on ajoute 3 600 000 millisecondes à l'heure courante val anHourFromNow = now.getTime() + (60 * 60 * 1000) assert(anHourFromNow > now.getTime()) //java.util.Calendar //pour manipuler les dates et heures de facon plus sophistiquée //instanciation selon les parametres locaux //et le fuseau horaire local val calendar = Calendar.getInstance() //initialisation du calendrier à la date de maintenant calendar.setTime(now) //détermine le jour de l'année auquel correspond la date courante val dayOfYear = calendar.get(Calendar.DAY_OF_YEAR) assert(dayOfYear < 366) //réinitialisation de la date courante calendar.set(2019, Calendar.MAY, 8) assertEquals(4, calendar.get(Calendar.DAY_OF_WEEK)) //à quel jour du mois correspond le deuxieme mercredi de mai 2019 //set(key,value) calendar.set(Calendar.YEAR, 2019) calendar.set(Calendar.MONTH, Calendar.MAY) calendar.set(Calendar.DAY_OF_WEEK, Calendar.WEDNESDAY) //defini à quel (n=2) semaine du mois est la date calendar.set(Calendar.DAY_OF_WEEK_IN_MONTH, 2) //extrait le jour du mois val dayOfMonth = calendar.get(Calendar.DAY_OF_MONTH) assertEquals(8, dayOfMonth) calendar.setTime(kotlinAnnounceDate) //ajoute 30j à la date calendar.add(Calendar.DATE, 30) val monthAfter = calendar.getTime() //date est elle avant ou apres? assertTrue(monthAfter.after(kotlinAnnounceDate)) } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">table des matières</a></p> </div> </div> </div> <div class="sect1"> <h2 id="java8date">dates et heures java8</h2> <div class="sectionbody"> <div class="paragraph"> <p>Java 8 introduit le nouveau package <strong><em>java.time</em></strong>, qui contient les classes de base qui<br> la plupart des développeurs travaillent avec. Il contient également quatre sous-packages:<br></p> </div> <div class="paragraph"> <p><strong><em>java.time.chrono</em></strong><br> Chronologies alternatives que les développeurs utilisant des systèmes de calendrier qui ne<br> suivre la norme ISO va interagir avec. Un exemple serait un cal japonais<br> système endurant.<br> <strong><em>java.time.format</em></strong><br> Contient le DateTimeFormatter utilisé pour convertir les objets de date et d’heure<br> dans une chaîne et également pour analyser les chaînes dans les objets de données et de temps.<br> <strong><em>java.time.temporal</em></strong><br> Contient les interfaces requises par les classes de date et d’heure de base et également<br> des abstractions (telles que des requêtes et des ajusteurs) pour des opérations avancées avec des dates.<br> <strong><em>java.time.zone</em></strong><br> Classes utilisées pour les règles de fuseau horaire sous-jacentes;<br> la plupart des développeurs n’auront pas besoin ce paquet.<br></p> </div> <div class="imageblock"> <div class="content"> <img src="../../img/java8-date-time.png" alt="java8 date time"> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">import java.time.LocalDate import java.time.Month import java.time.Period import java.time.YearMonth import java.time.temporal.* import java.util.HashMap import java.util.stream.Collectors import kotlin.test.Test class DatesHoursJava8Test { class BirthdayDiary { private val birthdays: MutableMap<String, LocalDate> init { birthdays = HashMap() } fun addBirthday( name: String, day: Int, month: Int, year: Int ): LocalDate { val birthday: LocalDate = LocalDate.of(year, month, day) birthdays[name] = birthday return birthday } fun getBirthdayFor(name: String): LocalDate? { return birthdays[name] } fun getAgeInYear(name: String, year: Int): Int { val period: Period = Period.between( birthdays[name], birthdays[name]!!.withYear(year) ) return period.getYears() } fun getFriendsOfAgeIn(age: Int, year: Int): Set<String> { return birthdays.keys.stream() .filter { p: String -> getAgeInYear(p, year) == age } .collect(Collectors.toSet()) } fun getDaysUntilBirthday(name: String): Int { val period: Period = Period.between( LocalDate.now(), birthdays[name] ) return period.getDays() } fun getBirthdaysIn(month: Month): Set<String> { return birthdays.entries.stream() .filter { (_, value): Map.Entry<String, LocalDate> -> value.getMonth() === month } .map<String> { (key): Map.Entry<String, LocalDate> -> key } .collect(Collectors.toSet()) } val birthdaysInCurrentMonth: Set<String> get() = getBirthdaysIn(LocalDate.now().getMonth()) val totalAgeInYears: Int get() = birthdays.keys.stream() .mapToInt { p: String -> getAgeInYear( p, LocalDate.now().getYear() ) } .sum() } //Les ajusteurs modifient les objets de date et d'heure. Supposons, par exemple, que nous voulions //renvoie le premier jour d'un trimestre qui contient un horodatage particulier : class FirstDayOfQuarter : TemporalAdjuster { override fun adjustInto(temporal: Temporal): Temporal? { val currentQuarter: Int = YearMonth.from(temporal) .get(IsoFields.QUARTER_OF_YEAR) return when (currentQuarter) { 1 -> LocalDate.from(temporal) .with(TemporalAdjusters.firstDayOfYear()) 2 -> LocalDate.from(temporal) .withMonth(Month.APRIL.value) .with(TemporalAdjusters.firstDayOfMonth()) 3 -> LocalDate.from(temporal) .withMonth(Month.JULY.value) .with(TemporalAdjusters.firstDayOfMonth()) 4 -> LocalDate.from(temporal) .withMonth(Month.OCTOBER.value) .with(TemporalAdjusters.firstDayOfMonth()) else -> null } } } enum class Quarter { FIRST, SECOND, THIRD, FOURTH } //Dans quel trimestre de l'année cette date se situe-t-elle ? class QuarterOfYearQuery : TemporalQuery<Quarter> { override fun queryFrom(temporal: TemporalAccessor): Quarter { val now = LocalDate.from(temporal) return if (now.isBefore(now.with(Month.APRIL).withDayOfMonth(1))) Quarter.FIRST else if (now.isBefore( now.with(Month.JULY) .withDayOfMonth(1) ) ) Quarter.SECOND else if (now.isBefore( now.with(Month.NOVEMBER) .withDayOfMonth(1) ) ) Quarter.THIRD else Quarter.FOURTH } } @Test fun `Dates et heures après java 8`() { val today = LocalDate.now() val currentMonth = today.month val firstMonthOfQuarter = currentMonth.firstMonthOfQuarter() val q = QuarterOfYearQuery() // Direct var quarter: Quarter? = q.queryFrom(LocalDate.now()) println(quarter) // Indirect quarter = LocalDate.now().query(q) println(quarter) val now = LocalDate.now() val fdoq: Temporal = now.with(FirstDayOfQuarter()) println(fdoq) } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">table des matières</a></p> </div> </div> </div> <div class="sect1"> <h2 id="arrCol">tableaux et collections</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="../../img/collections_classes_inheritance.png" alt="Classes de collections et héritage"> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">package playground.programming import java.util.* import kotlin.test.Test import kotlin.test.assertEquals import kotlin.test.assertFalse import kotlin.test.assertTrue class ArrayCollectionTest { @Test fun `Tableaux, collections`() { //Tableau //java.util.Arrays définit d'utiles méthodes de manipulation de tableaux, //y compris de tri et de recherche au sein d'un tableau val intArray = arrayOf(10, 5, 7, -3) //tri le tableau Arrays.sort(intArray) var pos = Arrays.binarySearch(intArray, 7) //la valeur 7 est trouvé a l'index 2 assertEquals(2, pos) //12 pas trouvé retourne une valeur negative assert(Arrays.binarySearch(intArray, 12) < 0) //les tableaux peuvent également etre triés //et faire l'objet d'une recherche val stringArray = arrayOf("le", "moment", "c'est") assertEquals("c'est", stringArray[2]) assertEquals("le", stringArray[0]) assertEquals("moment", stringArray[1]) Arrays.sort(stringArray) assertEquals("c'est", stringArray[0]) assertEquals("le", stringArray[1]) assertEquals("moment", stringArray[2]) //Arrays.equals() compare tous les éléments de deux tableaux //Arrays.clone() copie tous les elements du tableau dans un autre stringArray.forEachIndexed { i, it -> assertEquals(it, stringArray.clone()[i]) } val data = ByteArray(100) //Arrays.fill() initialise tous les éléments des deux tableaux //initalise tous les éléments à -1 Arrays.fill(data, -1) data.forEach { assertEquals(-1, it) } //attribue aux éléments 5, 6, 7, 8 et 9 la valeur -2 Arrays.fill(data, 5, 10, -2) ((5 until (10 - 1))).forEach { assertEquals(-2, data[it]) } //récupère le type de data val type = data::class.java //est ce que data est un tableau? assertTrue(type.isArray()) //est ce que data est un tableau de byte assertEquals(Byte::class.java, type.getComponentType()) //Collection val s = java.util.HashSet<String>() s.add("test") assertTrue(s.contains("test")) assertFalse(s.contains("test2")) s.remove("test") assertFalse(s.contains("test")) val ss = TreeSet<String>() ss.add("b") ss.add("a") ss.iterator().forEach { assertTrue(it == "a" || it == "b") } //liste doublement chainée var dll: List<String> = LinkedList<String>() //plus efficace val l = java.util.ArrayList<String>() l.addAll(ss) l.addAll(1, ss) val obj = l.get(1) val obj_prime = l[1] assertEquals(obj, obj_prime) l.set(3, "nouvel élément") l.add("test") l.add(0, "test2") l.removeAt(1) l.remove("a") assertFalse(l.contains("a")) l.removeAll(ss) assertFalse(l.containsAll(ss)) assertFalse(l.isEmpty()) assertTrue(l.isNotEmpty()) val sublist = l.subList(1, 3) val elements = l.toArray() l.clear() val m = HashMap<String, Integer>() m.put("clé", Integer(42)) m["clé"] = Integer(42) val value: Integer = m.get("clé")!! assertEquals(Integer(42), value) m.remove("clé") assertTrue(m.isEmpty()) val keys = m.keys assertTrue(keys.isEmpty()) val set = HashSet<String>() set.add("key_1") set.add("key_2") set.add("key_3") val members = set.toArray() assertEquals(3, members.size) val list = ArrayList<String>() list.add("items1") list.add("items2") list.add("items3") val items = list.toArray() assertEquals(3, items.size) //trie et recherche d'éléments sur les collections list.add("clé") //en premier on trie Collections.sort(list) //en kotlin list.sort() //en deuxieme on cherche //retourne l'index du premier trouvé sinon -1 pos = Collections.binarySearch(list, "clé") assertEquals(0, pos) val list1 = mutableListOf(1, 2, 3, 4, 5) val list2 = mutableListOf<Int>(0, 0, 0, 0, 0) //d'autres méthodes intéressantes concernant Collections //copie list1 dans list2, 2e parametre dans 1er parametre Collections.copy(list2, list1) //comparaison de la copy avec filter assertTrue(list1.filterIndexed { i: Int, it: Int -> it != list2[i] }.isEmpty()) //comparaison de la copy avec map list1.mapIndexed { index: Int, it: Int -> assertEquals(it, list2[index]) } //rempli avec des 0 Collections.fill(list2, 0) assertTrue(list2.none { it != 0 }) //le maximum assertEquals(5, Collections.max(list1)) //le minimum assertEquals(1, Collections.min(list1)) //renverse Collections.reverse(list) listOf("items3", "items2", "items1", "clé").mapIndexed { i: Int, it: String -> assertEquals(it, list[i]) } //mélange la list Collections.shuffle(list) //retourne un ensemble immuable possédant un seul élément 0 Collections.singleton(0) //renvoi un emballage immuable autour d'une liste Collections.unmodifiableList(list) //renvoi un emballage synchronisé autour d'une map, ensemble clé valeur Collections.synchronizedMap(m) //java.util.Properties un est objet key value } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">table des matières</a></p> </div> </div> </div> <div class="sect1"> <h2 id="sysProp">System.Properties</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html">System.Properties doc officielle</a></p> </div> <div class="paragraph"> <p>voici un tableau de quelques propriétés intéressantes<br> Ces propriétés sont intéressantes pour avoir des informations<br> sur le système hôte de la JVM.</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3343%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Key</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Meaning</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">file.separator</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Character that separates components of a file path. This is "/" on UNIX and "\" on Windows.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">java.class.path</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Path used to find directories and JAR archives containing class files. Elements of the class path are separated by a platform-specific character specified in the path.separator property.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">java.home</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Installation directory for Java Runtime Environment (JRE)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">java.vendor</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">JRE vendor name</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">java.vendor.url</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">JRE vendor URL</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">java.version</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">JRE version number</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">line.separator</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sequence used by operating system to separate lines in text files</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">os.arch</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Operating system architecture</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">os.name</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Operating system name</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">os.version</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Operating system version</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">path.separator</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Path separator character used in java.class.path</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">user.dir</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">User working directory</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">user.home</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">User home directory</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">user.name</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">User account name</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><a href="#toc">table des matières</a></p> </div> </div> </div> <div class="sect1"> <h2 id="threads">Threads</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">import java.text.DateFormat import java.util.* import kotlin.test.Test class ThreadsTest { @Test fun `threads test`() { //java.lang.Thread représente le thread fondamentale de l'API java //il existe deux manière de définir un thread //1) étendre la classe Thread ou une lambda en kotlin //2) implémenter l'interface Runnable, // puis passer une instance de cet objet Runnable au constructeur de Thread. val list1: List<Int> = List( size = 45, init = { (1..31).random() } ) println("list1$list1") //facon 1 val t = Thread { Collections.sort(list1) println("list1 sorted$list1") } t.start() val list2 = List( size = 45, init = { (1..31).random() } ) println("list2$list2") //facon 2 val sorter = BackgroundSorter(list2) sorter.start() //priorité des threads //tant qu'un thread de niveau de priorité supérieure n'est pas fini //alors celui de niveau inférieur ne peut s'exécuter //on définit un thread avec une priorité inférieur à la normale t.setPriority(Thread.NORM_PRIORITY - 1) //ici on définit un thread avec une priorité inférieur à la priorité //du thread courant t.setPriority(Thread.currentThread().getPriority() - 1) //Thread.yield() fait une pause pour laisser les autres threads de meme priorité s'exécuter } class BackgroundSorter(private val l: List<Int>) : Thread() { override fun run() { Collections.sort(l) println("list2 sorted$l") } } //pour l'arrêt du thread, plutôt qu'utiliser la fonction Thread.stop() // qui laisse la memoire dans un état non controlé. //utiliser la méthode tel que l'exemple pleaseStop() class DummyClock( private val df: DateFormat = DateFormat.getTimeInstance(DateFormat.MEDIUM), private var keepRunning: Boolean = true ) : Thread() { init { isDaemon = true start() } override fun run() { while (keepRunning) { println(df.format(Date())) try { sleep(1000) } catch (e: InterruptedException) { println(e.message) } } } fun pleaseStop() { keepRunning = false } } //java.util.Timer //java.util.TimerTask //ces classes permettent l'exécution de taches répétitives @Test fun `Timer et TimerTask test`() { DummyClock() } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">table des matières</a></p> </div> </div> </div> <div class="sect1"> <h2 id="regex">Expressions Régulières</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">import java.util.* import java.util.regex.Matcher import java.util.regex.Pattern import java.util.stream.Collectors import kotlin.test.Test import kotlin.test.assertEquals class RegularExpressionsTest { @Test fun `expressions régulières`() { val p: Pattern = Pattern.compile("honou?r") val caesarUK = "For Brutus is an honourable man" val mUK: Matcher = p.matcher(caesarUK) assertEquals(true, mUK.find(), "Should matches UK spelling") val caesarUS = "For Brutus is an honorable man" val mUS: Matcher = p.matcher(caesarUS) assertEquals(true, mUS.find(), "Should matches US spelling") } @Test fun `expressions régulières plus complexes`() { //Notez que nous devons utiliser \\ car nous avons besoin d'un littéral \ //et Java utilise un seul \ comme caractère d'échappement var pStr = "\\d" // Un chiffre numérique var text = "Apollo 13" var p = Pattern.compile(pStr) var m = p.matcher(text) print(pStr + " matches " + text + "? " + m.find()) println(" ; match: " + m.group()) pStr = "[a..zA..Z]" //N'importe quelle lettre p = Pattern.compile(pStr) m = p.matcher(text) print(pStr + " matches " + text + "? " + m.find()) println(" ; match: " + m.group()) //N'importe quel nombre de lettres, qui doivent toutes être comprises entre 'a' et 'j' //mais peut-être en majuscule ou en minuscule. pStr = "([a..jA..J]*)" p = Pattern.compile(pStr) m = p.matcher(text) print(pStr + " matches " + text + "? " + m.find()) println(" ; match: " + m.group()) text = "abacab" //'a' suivi de quatre caractères quelconques, suivi de 'b' pStr = "a....b" p = Pattern.compile(pStr) m = p.matcher(text) print(pStr + " matches " + text + "? " + m.find()) println(" ; match: " + m.group()) } @Test fun `Quelles chaînes correspondent à la regex ?`() { val pStr = "\\d" // Un chiffre numérique val p = Pattern.compile(pStr) val ls: List<String> = Arrays.asList("Cat", "Dog", "Ice-9", "99 Luftballoons") val containDigits: List<String> = ls.stream() .filter(p.asPredicate()) .collect(Collectors.toList()) assert(containDigits.contains("Ice-9")) assert(containDigits.contains("99 Luftballoons")) assertEquals(2, containDigits.size) } }</code></pre> </div> </div> <div class="sect2"> <h3 id="_tableau_regex_metacharacters">Tableau regex metacharacters</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7592%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Metacharacter</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">fonctionnalité</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Notes</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Caractère facultatif—zéro ou une instance</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">*</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Zéro ou plus du caractère précédent</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">+</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un ou plusieurs des caractères précédents</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">{M,N}</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Entre M et N instances du caractère précédent</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\d</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un chiffre</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\D</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un caractère non numérique</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\w</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un caractère de mot</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Chiffres, lettres et _</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\W</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un caractère sans mot</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\s</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un caractère d’espacement</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\S</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un caractère non blanc</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\n</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Caractère de saut de ligne</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\t</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Caractère de tabulation</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un caractère n’importe lequel</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N’inclut pas la nouvelle ligne en Java</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">[ ]</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tout caractère contenu entre crochets</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Appelé une classe de caractères</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">[^ ]</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tout caractère non contenu entre crochets</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Appelé une classe de caractères inversée</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">( )</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Construire un groupe d’éléments de motif</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Appelé un groupe (ou groupe de capture)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">|</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Définir des possibilités alternatives</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Implémente le OU logique</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">^</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Début de chaîne $ Fin de chaîne</p></td> <td class="tableblock halign-left valign-top"></td> </tr> </tbody> </table> <div class="paragraph"> <p>compléter <a href="https://www.codeurjava.com/2015/05/les-expressions-regulieres-avec-regex.html">avec</a></p> </div> </div> </div> </div> https://cheroliv.com/blog/2022/0047_memo_gradle_post.html Mon, 23 May 2022 00:00:00 +0000 blog/2022/0047_memo_gradle_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_도움말_보기">도움말 보기</a></li> <li><a href="#_jvm_시스템_속성을_정의합니다_d_system_prop">JVM 시스템 속성을 정의합니다: `-D, --system-prop</a></li> <li><a href="#_빌드_스크립트의_프로젝트_속성을_정의하세요_pmypropmyvalue">빌드 스크립트의 프로젝트 속성을 정의하세요 : `-Pmyprop=myvalue</a></li> <li><a href="#_gradle_시작_디렉터리를_지정합니다_기본값은_현재_디렉터리입니다">Gradle 시작 디렉터리를 지정합니다. 기본값은 현재 디렉터리입니다.</a></li> <li><a href="#_명령줄을_통해_param_component_속성을_오버라이드하세요">명령줄을 통해 'param_component' 속성을 오버라이드하세요:</a></li> <li><a href="#_일반_프로젝트에서_kotlin_dsl을_사용하여_소스_세트에_폴더_추가">일반 프로젝트에서 Kotlin DSL을 사용하여 소스 세트에 폴더 추가</a></li> <li><a href="#_groovy_dsl을_사용해_android_프로젝트의_소스_세트에_폴더_추가">Groovy DSL을 사용해 Android 프로젝트의 소스 세트에 폴더 추가</a></li> <li><a href="#_서브_모듈을_구축하고_테스트하지_마세요">서브 모듈을 구축하고 테스트하지 마세요</a></li> <li><a href="#_파일을_가져오다">파일을 가져오다</a></li> <li><a href="#_빌드의_의존성_표시">빌드의 의존성 표시</a></li> <li><a href="#_reduce_사용_예시_리스트를_문자열에_연결하기">reduce 사용 예시 : 리스트를 문자열에 연결하기</a></li> <li><a href="#_특정_작업의_설명을_검색하세요">특정 작업의 설명을 검색하세요</a></li> <li><a href="#_workingdir_루트에서_작업을_시작하려면_작업_앞에_를_붙이세요">workingDir 루트에서 작업을 시작하려면 작업 앞에 `:`를 붙이세요.</a></li> <li><a href="#_옵션_rerun_tasks를_사용하십시오">옵션 `--rerun-tasks`를 사용하십시오.</a></li> <li><a href="#_다른_디렉터리에서_특정_프로젝트의_작업을_실행">다른 디렉터리에서 특정 프로젝트의 작업을 실행</a></li> </ul> </div> <div class="sect1"> <h2 id="_도움말_보기">도움말 보기</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./gradlew --help</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_jvm_시스템_속성을_정의합니다_d_system_prop">JVM 시스템 속성을 정의합니다: `-D, --system-prop</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./gradlew -Dmyprop=myvalue #ou ./gradlew --system-prop myvalue</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_빌드_스크립트의_프로젝트_속성을_정의하세요_pmypropmyvalue">빌드 스크립트의 프로젝트 속성을 정의하세요 : `-Pmyprop=myvalue</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./gradlew -Pmyprop=myvalue #ou ./gradlew --project-prop myvalue</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_gradle_시작_디렉터리를_지정합니다_기본값은_현재_디렉터리입니다">Gradle 시작 디렉터리를 지정합니다. 기본값은 현재 디렉터리입니다.</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./gradlew -p ~/src/next_startup #ou ./gradlew --project-dir ~/src/next_startup</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_명령줄을_통해_param_component_속성을_오버라이드하세요">명령줄을 통해 'param_component' 속성을 오버라이드하세요:</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./gradlew -Pparam_component=CUSTOM_VALUE</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_일반_프로젝트에서_kotlin_dsl을_사용하여_소스_세트에_폴더_추가">일반 프로젝트에서 Kotlin DSL을 사용하여 소스 세트에 폴더 추가</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">sourceSets { getByName("test"){ java.srcDir("src/scripts/groovy") } getByName("test"){ java.srcDir("src/scripts/kscript") } getByName("test"){ java.srcDir("src/test/javascript") } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_groovy_dsl을_사용해_android_프로젝트의_소스_세트에_폴더_추가">Groovy DSL을 사용해 Android 프로젝트의 소스 세트에 폴더 추가</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">android { sourceSets { main.java.srcDirs += "src/main/../../../../ceelo/domain/src/main/java/" test.java.srcDirs += "src/test/../../../../ceelo/domain/src/test/java/" } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_서브_모듈을_구축하고_테스트하지_마세요">서브 모듈을 구축하고 테스트하지 마세요</h2> <div class="sectionbody"> <div class="paragraph"> <p>gradle build -x :excluded-module:check -x :excluded-module:assemble -x :excluded-module:build</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>파일 이동</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">tasks.register("moveWebappNode") { doLast { ant.withGroovyBuilder { "move"( "webapp/node_modules" to "$rootDir/webapp-src/node_modules", ) } } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_파일을_가져오다">파일을 가져오다</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">tasks.register<Tar>("tarWebapp") { dependsOn("moveWebappNpm") group = WEBAPP description = "tar webapp" doLast { setOf( "build", "target", "node_modules" ).forEach { dir -> exclude { it.name .dir } } archiveFileName.set("webapp.tar") destinationDirectory.set(File("${rootDir.absolutePath}$sep$WEBAPP_SRC")) } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_빌드의_의존성_표시">빌드의 의존성 표시</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">tasks.register("printDependencies") { description = "print project dependencies" group = WEBAPP doLast { println("${project.name} dependencies") mutableMapOf<String, Map<String, String>>( "buildDependencies" to buildDependencies, "domainDeps" to domainDeps, "domainTestDeps" to domainTestDeps, ).apply { putAll(appModules) } .forEach { module -> if (module.value.isNotEmpty()) { println("${module.key}:") module.value.forEach { println(dependency(it)) } println() } } } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_reduce_사용_예시_리스트를_문자열에_연결하기">reduce 사용 예시 : 리스트를 문자열에 연결하기</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">tasks.register("printWebappSrc") { description = "print webapp sources" group = WEBAPP doLast { webAppSrc .reduce { acc, s -> "$acc\n\t$s" } .run { println("$WEBAPP_SRC: $this\n") } } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_특정_작업의_설명을_검색하세요">특정 작업의 설명을 검색하세요</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./gradlew -q help --task foo</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_workingdir_루트에서_작업을_시작하려면_작업_앞에_를_붙이세요">workingDir 루트에서 작업을 시작하려면 작업 앞에 `:`를 붙이세요.</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./gradlew :foo</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_옵션_rerun_tasks를_사용하십시오">옵션 `--rerun-tasks`를 사용하십시오.</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./gradlew check --rerun-tasks</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_다른_디렉터리에서_특정_프로젝트의_작업을_실행">다른 디렉터리에서 특정 프로젝트의 작업을 실행</h2> <div class="sectionbody"> <div class="paragraph"> <p>옵션`-p` (ou <code>--project-dir</code>) 를 사용하면 Gradle 프로젝트의 경로를 지정하고 현재 디렉터리가 다를 경우에도 해당 작업을 실행할 수 있습니다.</p> </div> <div class="paragraph"> <p>예를 들어, 작업을 시작하려면`build`프로젝트 위치에 있는`~/projets/mon-autre-projet`다른 디렉터리에 있는 동안 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./gradlew -p ~/projets/mon-autre-projet build</code></pre> </div> </div> <div class="paragraph"> <p>이것은 중앙 위치에서 여러 프로젝트에 걸쳐 작업을 스크립트하는 데 특히 유용합니다.</p> </div> <div class="paragraph"> <p>참조 :</p> </div> <div class="ulist"> <ul> <li> <p><a href="https://docs.gradle.org/current/userguide/command_line_interface.html#sec:command_line_warnings">참조</a></p> </li> <li> <p><a href="https://docs.gradle.org/current/userguide/command_line_interface.html#sec:command_line_options">참조</a></p> </li> <li> <p><a href="https://stackoverflow.com/a/36178581/837404">토론</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2022/0038_training_kotlin_enum_sealed_class_post.html Tue, 17 May 2022 00:00:00 +0000 blog/2022/0038_training_kotlin_enum_sealed_class_post.html <div class="paragraph"> <p>밀봉된 클래스는 열거형이 아닙니다(키워드: enum).<br> 자바에서 온 당신은 기능 제공 열거형을 오버로드하려고 유혹을 느낄 수 있습니다: // 자바 코드</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">enum PizzaOrderStatus { ORDER_RECEIVED, PIZZA_BEING_MADE, OUT_FOR_DELIVERY, COMPLETED; public PizzaOrderStatus nextStatus() { switch (this) { case ORDER_RECEIVED: return PIZZA_BEING_MADE; case PIZZA_BEING_MADE: return OUT_FOR_DELIVERY; case OUT_FOR_DELIVERY: return COMPLETED; case COMPLETED:return COMPLETED; } } }</code></pre> </div> </div> <div class="paragraph"> <p>대신에, sealed 클래스를 사용할 수 있습니다:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">sealed class PizzaOrderStatus(protected val orderId: Int) { abstract fun nextStatus() : PizzaOrderStatus class OrderReceived(orderId: Int) : PizzaOrderStatus(orderId) { override fun nextStatus(): PizzaOrderStatus { return PizzaBeingMade(orderId) } } class PizzaBeingMade(orderId: Int) : PizzaOrderStatus(orderId) { override fun nextStatus(): PizzaOrderStatus { return OutForDelivery(orderId) } } class OutForDelivery(orderId: Int) : PizzaOrderStatus(orderId) { override fun nextStatus(): PizzaOrderStatus { return Completed(orderId) } } class Completed(orderId: Int) : PizzaOrderStatus(orderId) { override fun nextStatus(): PizzaOrderStatus { return this } } }</code></pre> </div> </div> <div class="paragraph"> <p>이 접근 방식의 장점은 이제 우리가 데이터를 전송할 수 있게 되었다는 것과 과 함께 상태:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">var status: PizzaOrderStatus = OrderReceived(123) while (status !is Completed) { status = when (status) { is OrderReceived -> status.nextStatus() is PizzaBeingMade -> status.nextStatus() is OutForDelivery -> status.nextStatus() is Completed -> status } }</code></pre> </div> </div> <div class="paragraph"> <p>일반적으로, sealed classes는 데이터를 연결하고 싶을 때 좋습니다. 국가.</p> </div> https://cheroliv.com/blog/2022/0036_training_kotlin_post.html Thu, 12 May 2022 00:00:00 +0000 blog/2022/0036_training_kotlin_post.html <div class="sect1"> <h2 id="_마인드_맵">마인드 맵</h2> <div class="sectionbody"> <div class="paragraph"> <p><span class="image"><img src="../../diagram/training_kotlin.png" alt="training_kotlin"></span></p> </div> </div> </div> <div class="sect1"> <h2 id="_함수형_프로그래밍">함수형 프로그래밍</h2> <div class="sectionbody"> <div class="paragraph"> <p>이 연습 문제는 책에서 발췌되었습니다:<br> 튜토리얼로 배우는 Kotlin 함수형 프로그래밍<br> Massimo Carli가 작성함<br> 저장소: <a href="https://github.com/kodecocodes/fpk-materials" class="bare">https://github.com/kodecocodes/fpk-materials</a></p> </div> <div class="sect2"> <h3 id="_구문">구문</h3> <div class="sect3"> <h4 id="_첫_프로그램_테스트">첫 프로그램 테스트</h4> <div class="paragraph"> <p>개념: 화면 표시, 기능<br> 첫 프로그램 테스트:https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/programming/FirstProgramTest.kt[source]+</p> </div> </div> <div class="sect3"> <h4 id="_연결_함수_테스트">연결 함수 테스트</h4> <div class="paragraph"> <p>개념: 메모리, 변수, 값, 객체, 함수 확장<br> ExampleUnitTest: <a href="https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/programming/ConcatFunctionTest.kt">출처</a>+</p> </div> </div> <div class="sect3"> <h4 id="_생일_메시지_테스트_출력">생일 메시지 테스트 출력</h4> <div class="paragraph"> <p>개념: 집합, 루프<br> <a href="https://developer.android.com/codelabs/basic-android-kotlin-training-first-kotlin-program?continue=https%3A%2F%2Fdeveloper.android.com%2Fcourses%2Fpathways%2Fandroid-basics-kotlin-one%23codelab-https%3A%2F%2Fdeveloper.android.com%2Fcodelabs%2Fbasic-android-kotlin-training-first-kotlin-program">Kotlin 소개</a><br> BirthdayMessageTestOutput:https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/programming/BirthdayMessageTestOutput.kt[출처]+</p> </div> </div> </div> <div class="sect2"> <h3 id="_코틀린_강의">코틀린 강의</h3> <div class="videoblock"> <div class="content"> <iframe src="https://www.youtube.com/embed/YRjY3jRrQYY?rel=0" frameborder="0" allowfullscreen></iframe> </div> </div> </div> <div class="sect2"> <h3 id="_자바_컬렉션에_대한_튜토리얼">자바 컬렉션에 대한 튜토리얼</h3> <div class="paragraph"> <p><a href="https://docs.oracle.com/javase/tutorial/collections/index.html" target="_blank" rel="noopener">컬렉션</a></p> </div> <div class="paragraph"> <p>컬렉션 인터페이스의 핵심<br> <span class="image"><img src="../../img/0036_training_kotlin_post/colls-coreInterfaces.gif" alt="컬렉션"></span><br></p> </div> </div> <div class="sect2"> <h3 id="_기본적인_기능">기본적인 기능</h3> <div class="sect3"> <h4 id="_선언적_x_명령형_접근">선언적 X 명령형 접근</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">package functional import kotlin.test.Test import kotlin.test.assertEquals class DeclarativeTests { val input = listOf( "123", "abc", "1ds", "987", "abdf", "1d3", "de1", "88", "101" ) fun imperativeSum(list: List<String>): Int { var sum = 0 for (item in list) { try { sum += item.toInt() } catch (_: NumberFormatException) { } } return sum } @Test fun `test imperative approach`() { imperativeSum(input).run { println("Sum $this") assertEquals(1299, this) } } fun isValidNumber(s: String) = try { s.toInt() true } catch (_: NumberFormatException) { false } fun declarativeSum(list: List<String>) = list .filter(::isValidNumber) .map(String::toInt) .sum() @Test fun `test declarative approach`() { assertEquals(1299, declarativeSum(input).apply { println("Sum $this") }) } }</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_연습_1_1">연습 1.1</h4> <div class="paragraph"> <p>sumInRange 함수를 구현하라, 이 함수는 값들을 더한다<br> 주어진 구간 내의 List<String>. 서명은:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">fun sumInRange(input: List<String>, range: IntRange): Int</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `Exercise 1_1`() { assertEquals(4, sumInRange( listOf("1", "10", "a", "7", "ad2", "3"), 1..5 ).apply { println("sumInRange 1..5: $this") } ) }</code></pre> </div> </div> <div class="paragraph"> <p>해보세요, 그리고 라와 함께 답변을 확인하세요https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/functional/DeclarativeTests.kt[해결책, 창="_blank].</p> </div> </div> <div class="sect3"> <h4 id="_고차_함수">고차 함수</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">package functional import java.io.ByteArrayOutputStream import java.io.PrintStream import java.lang.System.* import java.lang.Thread.sleep import kotlin.math.sign import kotlin.test.Test import kotlin.test.assertEquals class BasicsHOFTests { val ONE_SECOND = 1000L @Test fun `high order function`() { //capture de la sortie standard val standardOut: PrintStream? = out val outputStreamCaptor = ByteArrayOutputStream() setOut(PrintStream(outputStreamCaptor)) 3.times { println("Hello") } assertEquals( buildString { repeat(3) { append("Hello\n") } deleteAt(length - 1) }, outputStreamCaptor .toString() .trim() ) //libération de la sortie standard setOut(standardOut) } fun Int.times1(fn: () -> Unit) { for (i in 1..this) { fn() } } fun Int.times2(fn: () -> Unit) { for (i in 1..this) fn() } fun Int.times3(fn: () -> Unit) = (1..this).forEach { fn() } fun Int.times4(fn: () -> Unit) = repeat((1..this).count()) { fn() } fun Int.times(fn: () -> Unit) = (1..this).forEach { _ -> fn() } }</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_문제_1_2">문제 1.2</h4> <div class="paragraph"> <p>타입인 함수를 받아들이는 chrono를 구현하세요`() →`<br> 입력으로 받고 실행에 걸린 시간을 반환합니다. 서명 :<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">fun chrono(fn : () -> Unité) : Long</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `Exercise 1_2`() { val waitOneSec = { sleep(ONE_SECOND) } chrono(waitOneSec).apply { println("chrono: $this") assertEquals(1, sign) } }</code></pre> </div> </div> <div class="paragraph"> <p>해보고 당신의 답을 확인해 보세요와 함께https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/functional/BasicsHOFTests.kt[솔루션, windows="_blank].</p> </div> </div> <div class="sect3"> <h4 id="_구성">구성</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">package functional import kotlin.test.Test import kotlin.test.assertEquals fun double(x: Int): Int = 2 * x fun square(x: Int): Int = x * x fun squareAndDouble1(x: Int) = double(square(x)) infix fun <A, B, C> ((A) -> B).compose(g: (B) -> C) : (A) -> C = { a -> g(this(a)) } class CompositionTests { @Test fun composition_impure() { assertEquals(200, double(square(10))) assertEquals(200, squareAndDouble1(10)) } @Test fun composition_pure() { val squareAndDouble = ::square compose ::double assertEquals(200, squareAndDouble(10)) } }</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_순수_함수와_테스트_가능성">순수 함수와 테스트 가능성</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">package functional import java.io.ByteArrayOutputStream import java.io.PrintStream import java.lang.System.out import java.lang.System.setOut import kotlin.test.Test import kotlin.test.assertEquals var count = 0 //impure car une variable global subit un effet de bord fun impure(value: Int): Int { count++ return value + count } //impure car utilisation de la sortie standard qui fait muter le system fun addOneAndLog(x: Int): Int { val result = x + 1 println("New Value is $result") return result } //pure fun addOne(x: Int) = (x + 1).run { Pair(this, "New Value is $this") } class PureTests { @Test fun `impure fonction`() { assertEquals(3, impure(2)) val standardOut = out val outputStreamCaptor = ByteArrayOutputStream() setOut(PrintStream(outputStreamCaptor)) addOneAndLog(3) assertEquals( "New Value is 4", outputStreamCaptor .toString() .trim() ) setOut(standardOut) } @Test fun `pure fonction`() { addOne(3).run { assertEquals(4, first) assertEquals("New Value is 4", second) } } }</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_예외_처리">예외 처리</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">package functional import org.junit.jupiter.api.assertThrows import kotlin.Result.Companion.failure import kotlin.Result.Companion.success import kotlin.test.Test import kotlin.test.assertEquals //NumberFormatException est un effet de bord qui rend la fonction impure fun strToInt(str: String) = str.toInt() //pure fun strToIntOrNull(str: String) = try { str.toInt() } catch (nfe: NumberFormatException) { null } //pure avec gestion de l'exception plus élégante fun strToIntResult(str: String): Result<Int> = try { success(str.toInt()) } catch (nfe: NumberFormatException) { failure(nfe) } class ExceptionHandlingTests { @Test fun impure() { assertThrows<NumberFormatException> { strToInt("foo") } assertEquals(1, strToInt("1")) } @Test fun pure() { assertEquals(null, strToIntOrNull("foo")) assertEquals(1, strToIntOrNull("1")) } @Test fun `pure avec result`() { assertEquals(1, strToIntResult("1").getOrNull()) assertEquals( "For input string: \"foo\"", strToIntResult("foo") .exceptionOrNull() ?.message ) } }</code></pre> </div> </div> </div> </div> <div class="sect2"> <h3 id="_핵심_포인트">핵심 포인트</h3> <div class="ulist"> <ul> <li> <p>객체 지향 프로그래밍은 객체로 프로그래밍하는 것을 의미한다,</p> </li> </ul> </div> <div class="paragraph"> <p>함수형 프로그래밍은 함수를 사용해 프로그래밍하는 것을 의미합니다. 당신은 문제를 여러 하위 문제로 나누고, 그것을 모델링하여 함수들</p> </div> <div class="ulist"> <ul> <li> <p>고차 함수는 다른 함수를 입력으로 받거나 다른 함수를 반환합니다.</p> </li> </ul> </div> <div class="paragraph"> <p>반환 값처럼 동작합니다. 카테고리 이론은 구성의 이론이며, 당신은 이것을 이해하기 위해 사용합니다. 작업 프로그램에서 함수를 어떻게 구성하는지 순수 함수의 출력 값은 오직 그 입력 매개변수에만 의존하고, 그것 부작용이 없습니다.</p> </div> <div class="ulist"> <ul> <li> <p>부작용은 함수가 외부 세계에 미치는 무언가입니다. 이</p> </li> </ul> </div> <div class="paragraph"> <p>표준 출력에 로그가 될 수도 있고 전역 변수의 값이 수정될 수도 있습니다. 함수형 프로그래밍은 순수 함수에 대해 작동하지만, 또한 제공한다 불순한 함수를 순수한 함수로 변환하는 도구들 효과를 이동시켜 그것들을 순수하게 만들 수 있습니다 반환 값의 일부.</p> </div> <div class="ulist"> <ul> <li> <p>함수형 프로그래밍은 구성의 문제입니다.</p> </li> </ul> </div> <div class="paragraph"> <p>오류 관리는 부작용의 전형적인 사례이며, Kotlin은 도구를 제공합니다. 것들을 기능적으로 관리하기 위해</p> </div> </div> <div class="sect2"> <h3 id="_자바8_심화_람다_표현식_및_함수형_인터페이스">자바8 심화: 람다 표현식 및 함수형 인터페이스</h3> <div class="videoblock"> <div class="content"> <iframe src="https://www.youtube.com/embed/20waNRw6wMA?rel=0&list=PLzzeuFUy_Cng0wZhqbnkvWAW0d2fdVfyQ" frameborder="0" allowfullscreen></iframe> </div> </div> </div> <div class="sect2"> <h3 id="_범주론">범주론</h3> <div class="paragraph"> <p>수학적 범주 이론:</p> </div> <div class="videoblock"> <div class="content"> <iframe src="https://www.youtube.com/embed/LVHoROSF3KA?rel=0" frameborder="0" allowfullscreen></iframe> </div> </div> </div> <div class="sect2"> <h3 id="_함수의_기초">함수의 기초</h3> <div class="sect3"> <h4 id="_연습_2_1">연습 2.1</h4> <div class="paragraph"> <p>구분된 값을 매핑하는 함수의 예를 작성할 수 있나요?<br> 도메인이 범위 내에서 중복된 값을 가지는 경우, 아래 그림과 같이 f(b)와 f(c)와 같은 ?<br></p> </div> <div class="paragraph"> <p>해보고, 어떻게 했는지 보려면 챌린지 프로젝트의 솔루션을 확인해 보세요.<br> 링크를 따라가면 조언과 설명을 찾을 수 있습니다. <a href="https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/functional/BasicsHOFTests.kt">해결책</a>.<br></p> </div> </div> <div class="sect3"> <h4 id="_연습_2_2">연습 2.2</h4> <div class="paragraph"> <p>두 배 함수의 역함수를 작성할 수 있나요?<br> 역함수의 정의역과 치역은 무엇인가요?<br> 해결책을 보려면 챌린지 프로젝트와 부록 B를 확인하세요.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">fun chrono(fn : () -> Unité) : Long</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `Exercise 1_2`() { val waitOneSec = { sleep(ONE_SECOND) } chrono(waitOneSec).apply { println("chrono: $this") assertEquals(1, sign) } }</code></pre> </div> </div> <div class="paragraph"> <p>시도해 보세요 그리고 당신의 답을 확인해 보세요https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/functional/BasicsHOFTests.kt[해결책, windows="_blank].</p> </div> </div> </div> </div> </div> https://cheroliv.com/blog/2022/0031_memo_design_system_post.html Sun, 9 Jan 2022 00:00:00 +0000 blog/2022/0031_memo_design_system_post.html <div class="sect1"> <h2 id="_도구">도구</h2> <div class="sectionbody"> <div class="dlist"> <div class="title"><strong>삽화</strong></div> <dl> <dt class="hdlist1"><a href="https://undraw.co/">undraw.co</a></dt> <dd> <p>당신이 상상하고 만들 수 있는 모든 아이디어를 위한 오픈 소스 일러스트레이션.</p> </dd> <dt class="hdlist1"><a href="https://absurd.design/">황당한 디자인</a></dt> <dd> <p>의미 있는 어이없는 그림들</p> </dd> <dt class="hdlist1"><a href="https://drawkit.com/">drawkit.com</a></dt> <dd> <p>멋진 무료 일러스트레이션들. 주간 업데이트.</p> </dd> <dt class="hdlist1"><a href="https://icons8.com/">icons8.com</a></dt> <dd> <p>아이콘, 일러스트레이션, 사진, 음악, 디자인 도구</p> </dd> <dt class="hdlist1"><a href="https://blush.design/">홍조.디자인</a></dt> <dd> <p>아이콘, 일러스트레이션, 사진, 음악, 디자인 도구</p> </dd> <dt class="hdlist1"><a href="https://www.humaaans.com/">humaaans.com</a></dt> <dd> <p>사람 일러스트를 믹스 앤 매치하고 디자인 라이브러리와 함께 사용하세요.</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>색상</strong></div> <dl> <dt class="hdlist1"><a href="https://coolors.co/">coolors.co</a></dt> <dd> <p>초고속 색상 스키마 생성기!</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>경향</strong>.</div> <dl> <dt class="hdlist1"><a href="https://fr.pinterest.com">핀터레스트</a></dt> <dd> <p>시각적 아이디어 발견: 이미지, 비디오, 테마별 컬렉션</p> </dd> <dt class="hdlist1"><a href="https://dribbble.com">드리블</a></dt> <dd> <p>디자이너가 자신의 창작물을 공유하고 소통하는 플랫폼</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>UX/UI와 디자인 시스템</strong></div> <dl> <dt class="hdlist1"><a href="https://material.io/">구글 머터리얼 디자인</a></dt> <dd> <p>통일되고 적응 가능한 사용자 인터페이스를 위한 Google의 디자인 시스템</p> </dd> <dt class="hdlist1"><a href="https://developer.apple.com/design/human-interface-guidelines/">Apple Human Interface Guidelines</a></dt> <dd> <p>Apple의 iOS 및 macOS용 직관적인 애플리케이션 설계 권장 사항.</p> </dd> <dt class="hdlist1"><a href="https://www.uxpin.com/">UXPin</a></dt> <dd> <p>디자인 및 협업을 위한 프로토타입과 디자인 시스템을 생성하는 플랫폼</p> </dd> <dt class="hdlist1"><a href="https://www.frontify.com/">Frontify</a></dt> <dd> <p>브랜드 관리 및 디자인 시스템 플랫폼으로 일관성을 보장합니다.</p> </dd> <dt class="hdlist1"><a href="https://designsystemsrepo.com/design-systems/">디자인 시스템 레포</a></dt> <dd> <p>영감을 주는 리소스와 디자인 시스템 예시 모음</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>개발 프론트엔드</strong></div> <dl> <dt class="hdlist1"><a href="https://htmlcheatsheet.com" target=""_blank">htmlcheatsheet.com</a></dt> <dd> <p>HTML 치트시트</p> </dd> <dt class="hdlist1"><a href="https://fontawesome.com" target=""_blank">fontawesome.com</a></dt> <dd> <p>아이콘 라이브러리</p> </dd> <dt class="hdlist1"><a href="https://www.toptal.com/designers/htmlarrows/symbols/" class="bare">https://www.toptal.com/designers/htmlarrows/symbols/</a>[toptal.com/designers/htmlarrows/symbols, 창 = \"_blank\]</dt> <dd> <p>HTML의 네이티브 아이콘</p> </dd> <dt class="hdlist1"><a href="https://css-tricks.com/">CSS-Tricks</a></dt> <dd> <p>CSS에 필수적이며, 현대적인 프론트엔드 기사, 튜토리얼, 팁이 포함되어 있습니다.</p> </dd> <dt class="hdlist1"><a href="https://www.frontendmentor.io/">프론트엔드 멘토</a></dt> <dd> <p>실제 프로젝트를 기반으로 한 프론트엔드 코드 챌린지: 여러분의 실력을 향상시키세요.</p> </dd> <dt class="hdlist1"><a href="https://dev.to/">Dev.to</a></dt> <dd> <p>개발자 커뮤니티: 기사, 튜토리얼 및 프로젝트 공유</p> </dd> <dt class="hdlist1"><a href="https://codepen.io/">코드펜</a></dt> <dd> <p>온라인 코드 편집기 및 코드 스니펫과 데모를 공유하기 위한 커뮤니티.</p> </dd> </dl> </div> <div class="paragraph"> <p>AI 지원 프론트엔드 개발</p> </div> <div class="dlist"> <dl> <dt class="hdlist1"><a href="https://v0.dev/">v0.dev</a></dt> <dd> <p>v0는 자연어 설명을 코드와 사용자 인터페이스로 변환합니다.</p> </dd> <dt class="hdlist1"><a href="https://uizard.io/">위자드</a></dt> <dd> <p>Uizard는 디자인 모형(이미지, 스케치)를 HTML, CSS 및 React 코드로 변환하는 데 중점을 둡니다.</p> </dd> <dt class="hdlist1"><a href="https://www.usegalileo.ai/explore">usegalileo.ai</a></dt> <dd> <p>Galileo AI는 자연 언어로 원하는 인터페이스를 설명할 수 있게 해 주며, IA는 편집 가능한 Figma 디자인을 생성합니다.</p> </dd> <dt class="hdlist1"><a href="https://play.teleporthq.io/">TeleportHQ</a></dt> <dd> <p>TeleportHQ는 AI를 활용하여 시각적으로 웹사이트를 구축하고 배포할 수 있도록 돕는 로우코드 프론트엔드 개발 플랫폼입니다.</p> </dd> </dl> </div> </div> </div> https://cheroliv.com/blog/2020/0029_kubernetes_microk8s_docker_premiers_pas_post.html Tue, 3 Nov 2020 00:00:00 +0000 blog/2020/0029_kubernetes_microk8s_docker_premiers_pas_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://microk8s.io/docs/">microk8s 공식 문서</a>+</p> </div> </div> </div> <div class="sect3"> <h4 id="_마이크로k8s_패키지_설치">마이크로K8s 패키지 설치:</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"></code></pre> </div> </div> </div> https://cheroliv.com/blog/2020/0028_gradle_executer_un_processus_externe_depuis_une_tache_gradle_post.html Mon, 28 Sep 2020 00:00:00 +0000 blog/2020/0028_gradle_executer_un_processus_externe_depuis_une_tache_gradle_post.html <div class="sect3"> <h4 id="_gradle_kotlin_dsl">Gradle-Kotlin-DSL:</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin"></code></pre> </div> </div> </div> https://cheroliv.com/blog/2020/0027_kotlin_not_implemented_exception_not_implemented_error_post.html Sun, 27 Sep 2020 00:00:00 +0000 blog/2020/0027_kotlin_not_implemented_exception_not_implemented_error_post.html <div class="paragraph"> <p>NotImplementedException NotImplementedError, utilité pour les tests, ça permet de savoir, où on en est, et la cause du fail.<br> Pas encore implémenté, permet de lever la bonne exception.<br> Il y a :<br> <a href="http://commons.apache.org/proper/commons-lang/javadocs/api-release/org/apache/commons/lang3/NotImplementedException.html">org.apache.commons.lang3.NotImplementedException</a><br> <a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-not-implemented-error/">kotlin.NotImplementedError</a><br></p> </div> https://cheroliv.com/blog/2020/0026_untar_post.html Sat, 26 Sep 2020 00:00:00 +0000 blog/2020/0026_untar_post.html <div class="sect3"> <h4 id="_liens_interserver_net">Liens: <a href="https://www.interserver.net/tips/kb/extract-tar-gz-files-using-linux-command-line/">interserver.net</a></h4> </div> https://cheroliv.com/blog/2020/0025_gradle_rejouer_les_tests_meme_lorsque_les_tests_sont_UP-TO-DATE_post.html Fri, 25 Sep 2020 00:00:00 +0000 blog/2020/0025_gradle_rejouer_les_tests_meme_lorsque_les_tests_sont_UP-TO-DATE_post.html https://cheroliv.com/blog/2020/0024_docker_n_installe_pas_l_application_mais_tire_la_plutot_post.html Thu, 24 Sep 2020 00:00:00 +0000 blog/2020/0024_docker_n_installe_pas_l_application_mais_tire_la_plutot_post.html <div class="sect3"> <h4 id="_source_hackernoon_com">source: <a href="https://hackernoon.com/dont-install-postgres-docker-pull-postgres-bee20e200198">hackernoon.com</a></h4> </div> https://cheroliv.com/blog/2020/0023_gherkin_en_francais_post.html Wed, 23 Sep 2020 00:00:00 +0000 blog/2020/0023_gherkin_en_francais_post.html https://cheroliv.com/blog/2020/0022_gradle_cli_surcharger_un_parametre_post.html Tue, 22 Sep 2020 00:00:00 +0000 blog/2020/0022_gradle_cli_surcharger_un_parametre_post.html <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- ---- $ ./gradlew -Pparam_component=CUSTOM ---- ----</code></pre> </div> </div> https://cheroliv.com/blog/2020/0021_memo_git_post.html Mon, 21 Sep 2020 00:00:00 +0000 blog/2020/0021_memo_git_post.html <div class="sect3"> <h4 id="_출처">출처:</h4> <div class="paragraph"> <p>*https://xenovation.com/blog/source-control-management/git/how-to-change-remote-git-repository[크세노베이션] *https://intellipaat.com/community/3102/git-show-remote-url-how-can-i-determine-the-url-that-a-local-git-repository-was-originally-cloned-from[intellipaat]</p> </div> </div> <div class="sect3"> <h4 id="_git에서_원격_저장소_변경하기">Git에서 원격 저장소 변경하기</h4> <div class="paragraph"> <p>현재 원격 저장소 URL 표시:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"></code></pre> </div> </div> </div> https://cheroliv.com/blog/2020/0021_aspirer_depuis_une_URL_post.html Sun, 20 Sep 2020 00:00:00 +0000 blog/2020/0021_aspirer_depuis_une_URL_post.html <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- ---- $ wget -r -k -np http://site.com/docs/manual/ ---- 대상 폴더를 지정하려면 -P 인수를 추가한 다음 경로를 제공하세요. ----</code></pre> </div> </div> https://cheroliv.com/blog/2020/0020_creer_un_disk_bootable_post.html Sat, 19 Sep 2020 00:00:00 +0000 blog/2020/0020_creer_un_disk_bootable_post.html <div class="sect3"> <h4 id="_liens_etcher">Liens: <a href="https://www.balena.io/etcher/">etcher</a></h4> </div> https://cheroliv.com/blog/2020/0019_dezipper_en_CLI_dans_un_dossier_cible_post.html Fri, 18 Sep 2020 00:00:00 +0000 blog/2020/0019_dezipper_en_CLI_dans_un_dossier_cible_post.html <div class="sect3"> <h4 id="_링크_askubuntu">링크: <a href="https://askubuntu.com/questions/86849/how-to-unzip-a-zip-file-from-the-terminal">askubuntu</a></h4> <div class="paragraph"> <p>특정 대상 폴더로 추출하려면, 다음과 같이 사용할 수 있습니다: <code>` $ unzip fichier.zip -d 대상_디렉토리 </code>` 소스 디렉터리와 대상 디렉터리가 동일한 경우, 단순히 다음과 같이 할 수 있습니다: <code>` $ unzip file.zip </code>`</p> </div> </div> https://cheroliv.com/blog/2020/0018_Afficher_la_somme_des_tailles_de_fichier_dans_la_liste_des_r%C3%A9pertoires_post.html Thu, 17 Sep 2020 00:00:00 +0000 blog/2020/0018_Afficher_la_somme_des_tailles_de_fichier_dans_la_liste_des_r%C3%A9pertoires_post.html <div class="sect3"> <h4 id="_liens_stackexchange">Liens: <a href="https://unix.stackexchange.com/questions/72661/show-sum-of-file-sizes-in-directory-listing">stackexchange</a></h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- ---- $ du -ach --exclude "./.*" /home/troll/ ---- ----</code></pre> </div> </div> </div> https://cheroliv.com/blog/2020/0017_detruire_une_branch_sur_github_post.html Wed, 16 Sep 2020 00:00:00 +0000 blog/2020/0017_detruire_une_branch_sur_github_post.html <div class="sect3"> <h4 id="_détruire_une_branch_sur_github">Détruire une branch sur github</h4> </div> <div class="sect3"> <h4 id="_lien_gist">Lien: <a href="https://gist.github.com/cheroliv/921a13ed23ae6d4d66af8d43dd536987">gist</a></h4> </div> https://cheroliv.com/blog/2020/0016_asciidoc_markdown_memo_post.html Tue, 15 Sep 2020 00:00:00 +0000 blog/2020/0016_asciidoc_markdown_memo_post.html <div class="paragraph"> <div class="title">Pourquoi asciidoc ou markdown ? Ici, je m’oriente vers asciidoc, car j’ai déjà quelques tickets écris en asciidoc.<br></div> <p>Asciidoc est un langage de balisage, qui permet de produire du contenu, en apportant une mise en page qui garde le texte lisible pour un humain.<br> C’est une façon de standardiser les traitements de textes pour des contenus simples sans logiciel supplémentaire.</p> </div> <div class="ulist"> <div class="title">Liens :</div> <ul> <li> <p><a href="https://blog.oxiane.com/2018/06/13/asciidoc-documentation-as-code/" target="_blank" rel="noopener">@jmdoudoux sur blog.oxiane.com</a> [asciidoc]</p> </li> <li> <p><a href="https://powerman.name/doc/asciidoc" target="_blank" rel="noopener">powerman.name</a> [asciidoc]</p> </li> </ul> </div> https://cheroliv.com/blog/2019/0013_how-to-install-a-deb-file_post.html Mon, 19 Aug 2019 00:00:00 +0000 blog/2019/0013_how-to-install-a-deb-file_post.html <div class="paragraph"> <p>명령줄에서 .deb 파일을 통해 Debian 패키지를 설치하려면.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ sudo dpkg -i /chemin/du/fichier/deb/</code></pre> </div> </div> <div class="paragraph"> <p>여기서 보기 위해https://unix.stackexchange.com/questions/159094/how-to-install-a-deb-file-by-dpkg-i-or-by-apt[참고]+</p> </div> https://cheroliv.com/blog/2019/0011_gradle_configuration_ide_jbake_content_post.html Fri, 16 Aug 2019 00:00:00 +0000 blog/2019/0011_gradle_configuration_ide_jbake_content_post.html <div class="paragraph"> <p>Dans un projet applicatif piloté par le gestionnaire de build Gradle<br> il est plus agréable d’avoir la visibilité sur tous les dossiers<br> participant au développement de l’application,<br> comme des dossiers de ressources qui ne sont pas<br> dans les chemins par convention.<br> Par exemple je veux que le dossier src/jbake,<br> soit visible en tant ‘resource folder’,<br> il est possible de le faire en rentrant dans la configuration du projet,<br> dans les wizards de l’IDE. Cependant cette option n’est pas sauvegardée au rechargement suivant<br> du projet Gradle dans l’IDE. Pour apporter cette configuration de façon permanente<br> la solution est de surcharger la configuration des chemins de sources<br> dans le fichier de configuration build.gradle tel que aux lignes 18, 19, 20 et 21 :<br> build.gradle<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">plugins { id "java" id "groovy" id "org.jbake.site" version "5.0.0" id "org.ajoberstar.git-publish" version "2.1.1" } repositories { mavenCentral() jcenter() } group project_group version project_version sourceSets { main { java { srcDirs = [] } groovy { srcDirs =["src/main/java", "src/main/groovy"] } resources { srcDirs =[ "src/main/resources", "src/jbake"//in order to get site src content in the IDE ] } } test { java { srcDirs = [] } groovy { srcDirs =["src/test/java", "src/test/groovy"] } } } test { useJUnitPlatform() } configurations { ivy } dependencies { ivy "org.apache.ivy:ivy:$ivy_version" implementation "org.codehaus.groovy:groovy-all:$groovy_version" implementation "org.asciidoctor:asciidoctor-java-integration:$asciidoctor_java_integration_version" implementation "org.freemarker:freemarker:$freemarker_version" testImplementation "org.junit.jupiter:junit-jupiter-api:$junit5_version" testRuntimeOnly "org.junit.jupiter:junit-jupiter-engine:$junit5_version" } gitPublish { repoUri = github_pages_blog_repository branch = git_branch contents { from(file(jbake_content_from)) { into jbake_content_to } } } tasks.withType(GroovyCompile) { groovyClasspath += configurations.ivy }</code></pre> </div> </div> https://cheroliv.com/blog/2019/0010_gradle_groovy_script_grab_ivy_configuration_post.html Wed, 14 Aug 2019 00:00:00 +0000 blog/2019/0010_gradle_groovy_script_grab_ivy_configuration_post.html <div class="paragraph"> <p>티켓의 주제는 Gradle 빌드 스크립트의 구성이다.<br> Groovy 스크립트를 참조하지 않고 사용하고 싶어요.<br> 내가 첨부한 Gradle 프로젝트에서<br> 나는 Gradle 외부에서 이 Groovy 스크립트를 실행할 수 있기를 원한다.<br> 외부 의존성 검색을 위한 Ivy 어노테이션이 없이<br> 성능 또는 컴파일 문제를 일으키지 않는다<br> Gradle 빌드 스크립트의.<br> 구성을 설명하기 위해 두 개의 스크립트를 사용합니다:<br> Gradle 빌드 스크립트와 Groovy 스크립트.<br> Groovy 스크립트는 시작 부분에서 2번째 줄에 포함됩니다,<br> 외부 종속성을 끌어오는 명령어<br> 의존성 관리자 ivy를 사용해서.<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-Groovy hljs" data-lang="Groovy">#!/usr/bin/env groovy @Grab("commons-io:commons-io:2.6") import org.apache.commons.io.FileUtils static String getSeparator() { System.getProperty("file.separator") } String from = "${System.getProperty("user.home")}${separator}.config${separator}transmission${separator}torrents" String to = "${System.getProperty("user.home")}${separator}Documents${separator}torrents_completed" File fromDlDir = new File("${System.getProperty("user.home")}${separator}Téléchargements") File fromDir = new File(from) File toDir = new File(to) Collection<File> torrentFiles = FileUtils.listFiles( fromDir, ["torrent"] as String[], false) torrentFiles.addAll(FileUtils.listFiles( fromDlDir, ["torrent", "torrent.added"] as String[], false)) torrentFiles.empty ?: torrentFiles.each { it -> FileUtils.copyFileToDirectory(it, toDir) } println torrentFiles.size()</code></pre> </div> </div> <div class="paragraph"> <p>build.gradle 파일에서 이제 어떻게 조화를 맞출지 봅시다<br> 두 가지 의존성 관리자, Ivy와 Gradle. 두 사이의 합의는 선에서 이루어집니다:<br> 26, 30, 37, 38 et 39<br> 그러면 나는 내 Groovy 스크립트를 수동으로 실행할 수 있다,<br> 그리고 Gradle 컴파일은 @Grab에 의해 방해받지 않습니다.<br> Groovy 스크립트의 종속성은 Gradle에 제공할 필요가 없습니다.<br> 하지만 나는 Gradle에서 Groovy 스크립트를 실행할 수 없습니다.<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-Groovy hljs" data-lang="Groovy">plugins { id "java" id "groovy" } repositories { mavenCentral() jcenter() } sourceSets { main { java { srcDirs = [] } groovy { srcDirs =["src/main/java", "src/main/groovy"] } resources { srcDirs =["src/main/resources"] } } test { java { srcDirs = [] } groovy { srcDirs =["src/test/java", "src/test/groovy"] } } } configurations { ivy } dependencies { ivy "org.apache.ivy:ivy:$ivy_version" implementation "org.codehaus.groovy:groovy-all:$groovy_version" } tasks.withType(GroovyCompile) { groovyClasspath += configurations.ivy }</code></pre> </div> </div> <div class="paragraph"> <p>티켓 참조에https://stackoverflow.com/a/18174033/837404[스택오버플로우]</p> </div> https://cheroliv.com/blog/2019/0009_groovy_algebre_pgcd_ppmc_post.html Tue, 13 Aug 2019 00:00:00 +0000 blog/2019/0009_groovy_algebre_pgcd_ppmc_post.html <div class="sect2"> <h3 id="_ppmc">PPMC</h3> <div class="paragraph"> <p><a href="https://fr.wikipedia.org/wiki/Plus_petit_commun_multiple">위키 PPMC 또는 최소 공배수</a></p> </div> <div class="paragraph"> <p>AlgebraUtils.groovy<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">package com.cheroliv.misc import groovy.transform.CompileStatic @CompileStatic class AlgebraUtils { /** * Great common divisor * Plus grand commun diviseur(pgcd) * Great Common Divisor * @param a * @param b * @return */ static Integer gcd(Integer a, Integer b) { !b ? a : gcd(b, a % b) } /** * Least common multiple * Plus petit commun multiplicateur(ppmc) * @param a * @param b * @return */ static BigInteger lcm(Integer a, Integer b) { (a * b / gcd(a, b)) as BigInteger } static void main(String... args) { Integer a = 96 Integer b = 28 println "gcd($a, $b) = ${gcd(a, b)}" a = 790 b = 990 println "lcm($a, $b) = ${lcm(a, b)}" } }</code></pre> </div> </div> <div class="paragraph"> <p>결과:</p> </div> <div class="paragraph"> <p>gcd(96, 28) = 4 최소공배수(790, 990) = 78210</p> </div> </div> https://cheroliv.com/blog/2019/0008_bash_find_trouver_fichiers_par_extension_post.html Mon, 12 Aug 2019 00:00:00 +0000 blog/2019/0008_bash_find_trouver_fichiers_par_extension_post.html <div class="paragraph"> <p>이름 기준으로 파일을 검색하고 있습니다: 확장자가 .h와 .cpp인 파일 목록</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ find . -name '*.h' -o -name '*.cpp' + +</code></pre> </div> </div> <div class="paragraph"> <div class="title">h 및 .cpp 확장자를 가진 파일 목록<br></div> <p>결과가 list_of_txt_files.list 파일에 저장됩니다.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ find . -name '*.h' -o -name '*.cpp' -print > list_of_txt_files.list</code></pre> </div> </div> <div class="paragraph"> <p>저는 확장자가 .chm인 파일의 목록을 찾고 있습니다.<br> 그리고 나는 이 목록을 파괴한다.<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ find . -name "*.chm" -type f -delete</code></pre> </div> </div> https://cheroliv.com/blog/2019/0015_projet_avec_methodologie_en_cascade_post.html Thu, 1 Aug 2019 00:00:00 +0000 blog/2019/0015_projet_avec_methodologie_en_cascade_post.html <div class="sect2"> <h3 id="_analyser_et_receuillir_les_besoins">Analyser et receuillir les besoins</h3> </div> <div class="sect2"> <h3 id="_definir_la_gestion_de_projet">Definir la gestion de projet</h3> <div class="imageblock"> <div class="content"> <img src="../../diagram/definir_projet.png" alt="definir la gestion de projet"> </div> </div> <div class="imageblock"> <div class="content"> <img src="../../img/triangle_qcd.png" alt="triangle_qcd"> </div> </div> </div> <div class="sect2"> <h3 id="_contextualiser_le_projet">Contextualiser le projet</h3> </div> <div class="sect2"> <h3 id="_analyser_et_recueillir_des_besoins">Analyser et recueillir des besoins</h3> <div class="sect3"> <h4 id="_formuler_les_objectifs_et_livrables">Formuler les objectifs et livrables</h4> </div> </div> <div class="sect2"> <h3 id="_décrypter_une_grille_de_lecture">Décrypter une grille de lecture</h3> </div> <div class="sect1"> <h2 id="_cadrez_le_projet_avec_votre_équipe">Cadrez le projet avec votre équipe</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="../../img/conductor.png" alt="chef d’orchestre"> </div> </div> <div class="sect2"> <h3 id="_consulter_les_experts_pour_trouver_la_solution">Consulter les experts pour trouver la solution</h3> </div> <div class="sect2"> <h3 id="_choisir_une_méthodologie_de_gestion_de_projet">Choisir une méthodologie de gestion de projet</h3> <div class="imageblock"> <div class="content"> <img src="../../img/cascading_planning.png" alt="planning en cascade"> </div> </div> <div class="imageblock"> <div class="content"> <img src="../../img/Cycle_V_details.jpeg" alt="cycle en V"> </div> </div> </div> </div> </div> https://cheroliv.com/blog/2019/0014_list_all_databases_in_postgresql_post.html Tue, 30 Jul 2019 00:00:00 +0000 blog/2019/0014_list_all_databases_in_postgresql_post.html <div class="paragraph"> <p>설치하고 싶지 않아https://www.pgadmin.org/[pgAdmin] ou <a href="http://phppgadmin.sourceforge.net/">phppgadmin</a> 명령줄에 모든 것이 존재하지만.<br> 이를 위해서는 터미널을 실행하고 postgres 사용자로 로그인해야 합니다.<br> postgres 사용자만이 기본적으로 psql 애플리케이션을 실행할 권한이 있습니다. psql은 명령줄 클라이언트입니다. (Empty output)<a href="https://fr.wikipedia.org/wiki/Interface_en_ligne_de_commande">CLI</a>) postgresql,<br> 터미널에서 명령줄을 통해 온라인 데이터베이스와 대화하기 위해<br> 연결하려면 터미널을 실행하고 이것을 입력하세요:<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ sudo -i -u postgres</code></pre> </div> </div> <div class="paragraph"> <p>PostgreSQL 명령 프롬프트에 직접 연결하고 이동하려면 다음을 입력하세요 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ sudo -i -u postgres psql</code></pre> </div> </div> <div class="paragraph"> <p>PostgreSQL 인스턴스의 데이터베이스를 나열하려면 다음 명령어 :<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-SQL hljs" data-lang="SQL">postgres=# \l</code></pre> </div> </div> <div class="paragraph"> <p>결과:</p> </div> <div class="paragraph"> <p>데이터베이스 목록 이름 | 소유자 | 인코딩 | 콜레이션 | 문자 유형 | 접근 권한</p> </div> <div class="paragraph"> <p>fiber | tech | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | =Tc/tech<br> | | | | | tech=CTc/tech fiberdev | tech | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | =Tc/tech<br> | | | | | tech=CTc/tech fiberweb | tech | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | =Tc/tech<br> | | | | | tech=CTc/tech postgres | postgres | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | template0 | postgres | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | =c/postgres<br> | | | | | postgres=CTc/postgres template1 | postgres | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | =c/postgres<br> | | | | | postgres=CTc/postgres (6줄)</p> </div> <div class="paragraph"> <p>q를 눌러 결과 표시에서 나가세요<br> <br> postgresl 인스턴스의 스키마를 나열하려면.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-sql hljs" data-lang="sql">postgres=# SELECT schema_name FROM information_schema.schemata;</code></pre> </div> </div> <div class="paragraph"> <p>결과</p> </div> <div class="paragraph"> <p>공개 information_schema pg_catalog pg_toast_temp_1 pg_temp_1 pg_toast (6줄)</p> </div> <div class="paragraph"> <p>ou</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-sql hljs" data-lang="sql">postgres=# SELECT nspname FROM pg_catalog.pg_namespace;</code></pre> </div> </div> <div class="paragraph"> <p>결과</p> </div> <div class="paragraph"> <p>pg_toast pg_temp_1 pg_toast_temp_1 pg_catalog information_schema 대중 (6줄)</p> </div> https://cheroliv.com/blog/2019/0007_groovy_rename_recursively_files_post.html Mon, 29 Jul 2019 00:00:00 +0000 blog/2019/0007_groovy_rename_recursively_files_post.html <div class="paragraph"> <p>Mon lecteur de vidéo sur ma TV a sa façon de passer<br> d’un fichier à l’autre en lecture continue<br> et son mode de lecture est de passer de 1…​..mp4 à 10…​.mp4,<br> et non pas de 1…​mp4 à 2…​.mp4.<br> Le problème est qu’il y a près de 900 fichiers et dossiers.<br> Bingo un super cas d’utilisation de Groovy pour manipuler<br> des fichiers, renommage, recherche de motif dans le nom du fichier<br> ou dossier.<br> Ici le but est de changer les noms commençant par<br> un chiffre et dont le second caractère du nom<br> n’est pas un chiffre, j’ajouterai à ce nom un 0 au début<br></p> </div> <div class="paragraph"> <p>renameFilesToStartWithTwoDigit.groovy<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">#!/usr/bin/env groovy /** * get a crossplateform separator * @return */ static String getSeparator() { System.getProperty("file.separator") } /** * rename file * @param file * @param newName * @return the renamed file */ static File rename(File file, String newName) { assert file.renameTo(file .parentFile.path + getSeparator() + newName) new File(file .parentFile.path + getSeparator() + newName) } String rootFolderPath = System.getProperty("user.home") + "/Bureau/ng-courses/Udemy - Angular 7 " + "(formerly Angular 2) - The Complete Guide" File rootFolder = new File(rootFolderPath) assert rootFolder.exists() assert rootFolder.directory assert rootFolder.canRead() List<File> dirList = new ArrayList<>() //Adding rootFolder in dirList // just in case there is some files in it dirList.add(rootFolder) //looping to get list of directories //recursively inside rootFolder rootFolder.traverse { File file -> !file.directory ?: dirList.add(file) } //looping through dirList //to rename directories filling criterias for (int i = dirList.size() - 1; i >= 0; i--) { Character[] chars = dirList.get(i).name.chars !(chars[0].digit && !chars[1].digit) ?: dirList.set(i, rename(dirList.get(i), "0${dirList.get(i).name}")) if (dirList.get(i).directory) { //looping through directory //to rename file filling criterias dirList.get(i).listFiles().each { File f -> Character[] cs = f.name.chars !(cs[0].digit && !cs[1].digit) ?: rename(f, "0${f.name}") } } }</code></pre> </div> </div> https://cheroliv.com/blog/2019/0006_groovy_find_files_copy_to_post.html Fri, 19 Jul 2019 00:00:00 +0000 blog/2019/0006_groovy_find_files_copy_to_post.html <div class="paragraph"> <p>Le but de ce script est de rechercher des fichiers,<br> à partir d’un répertoire parent; récupérer la sélection<br> dans une liste. Enfin copier cette liste de fichiers<br> dans un répertoire destination cela en Groovy.</p> </div> <div class="paragraph"> <p>findCopyTo.groovy<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">#!/usr/bin/env groovy @Grab("commons-io:commons-io:2.6") import groovy.io.FileType import org.apache.commons.io.FileUtils /** * un separateur OS independant * @return */ static String getSep() { System.getProperty("file.separator") } /** * la liste des fichiers dont le titre contient un item * de la liste des motifs * * @param path * @param motifs * @return la liste des chemins complet de fichiers */ static List<String> findFilesContainingMotifs( String path, List<String> motifs) { List<String> filePathResultList = new ArrayList<>() new File(path) .eachFileRecurse(FileType.FILES) { if (it.name.toLowerCase().contains('cucumber')) { filePathResultList.add it.path } } filePathResultList } /** * copy vers la liste des fichiers * @param files * @param to */ static void copyFilesTo(List<String> files, String to) { File toDirDest = new File(to) files.each { String filepath -> File file = new File(filepath) //si le dernier caractere de to n'est pas un separateur // alors ajoute le a la chaine (to.substring(to.length() - 1) == sep) ?: to.concat(sep) if (to + file.name != filepath) { FileUtils.copyFileToDirectory(file, toDirDest) file.delete() } } } /** * la list des arguments */ String userName = System.getProperty("user.name") List<String> motifs = ['cucumber'] String path = "/media/$userName/320/Books/" String to = "/media/$userName/320/Books/bdd/" /** * lappel aux methodes */ copyFilesTo(findFilesContainingMotifs(path, motifs), to) //affiche moi les fichiers déplacés findFilesContainingMotifs(path, motifs).each { println it }</code></pre> </div> </div> https://cheroliv.com/blog/2019/0005_groovy_manipulation_files_post.html Thu, 18 Jul 2019 00:00:00 +0000 blog/2019/0005_groovy_manipulation_files_post.html <div class="paragraph"> <p>Ici je vais m’intéresser au chargement d’une propriété dans un build projet <a href="https://docs.gradle.org/current/userguide/userguide.html">gradle</a><br> sans que celle ci soit disponible dans le code.<br> La propriété sera défini dans le fichier gradle.properties du dossier ~/.gradle/gradle.properties<br> ~ est un raccourcie de la variable symbolique HOME_PATH représentant la racine utilisateur de session: le <a href="https://fr.wikipedia.org/wiki/R%C3%A9pertoire_personnel">répertoire personnel</a>.<br> De la même façon dans un build projet <a href="https://maven.apache.org/guides/index.html">maven</a>, avec ~/.m2/settings.xml Le but de ce script c’est de supprimer les fichiers qui correspondraient aux motifs énoncés<br> dans la variable strCriteria. Pour cela je vais utiliser les <a href="https://fr.wikipedia.org/wiki/Fermeture_(informatique)">closures</a>: each, findAll, collect<br> ainsi que la classe StringTokenizer qui va découper en morceau ma chaîne de critères<br> pour en récupérer une liste de strings. Si un des fichiers de mon dossier à nettoyer contient un des motif dans son nom<br> alors il sera un candidat à la destruction en étant ajouté à la liste résultat.<br> Et à la dernière ligne un petit exemple d’<a href="https://en.wikipedia.org/wiki/Elvis_operator">Elvis operator</a><br> filemanip.groovy<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">#!/usr/bin/env groovy //Mes criteres de selection des fichiers à detruire String strCriteria = "Dummies Dummie ajax Objective-C Windows blackberry " + "wordpress joomla ios c# f# rails ruby flex asp flash Dreamweaver adobe " + "CoffeeScript c++ .chm .epub .rar .zip .tar drupal drupals .net php javascript " + ".js iphone ipad js _js facebook gwt vaadin linq python py zope window " + "3D scala gaming active_directory tomcat jboss glassfish microsoft 2d " + "lego blogger blog cocoa dojo dom dotnetnuke eclipse .gz unity sharepoint " + ".tgz iwork filemaker .doc .txt" //repertoire personnel String userDir = System.getProperty("user.home") //un separateur de chemin crossplatform String sep = System.getProperty("file.separator") //la variable symbolique String sym_books_vrac_path = "books_vrac_path" //le chemin de mon fichier gradle.properties hors projet String propertiesFilePath = userDir .concat("${sep}.gradle${sep}gradle.properties") File propertiesFile = new File(propertiesFilePath) //je m'aassure que le fichier existe et que ce n'est pas un dossier assert propertiesFile.exists() && !propertiesFile.directory Properties gradleProperties = new Properties() //on boucle avec un inpustream sur le fichier //gradle.properties pour peupler ma variable gradleProperties propertiesFile.withInputStream { InputStream it -> gradleProperties.load(it) } //le chemin du dossier books_vrac est la valeur de notre clé books_vrac_path String pathVracDir = gradleProperties.get(sym_books_vrac_path) //j'ai récuperé tous ces livres en tapant cette commande dans le terminal //wget -m -np -c -R "index.html*" "http://the-eye.eu/public/Books/IT%20Various/" //on ouvre le dossier dont le chemin est dans la variable pathVracDir // on s'assure qu'il existe et que c'est un dossier File vracDir = new File(pathVracDir) assert vracDir.exists() && vracDir.directory //separer les élèments de ma liste de critère StringTokenizer tokenizer = new StringTokenizer(strCriteria) //la liste de critere List<String> criteriaList = new ArrayList<>() //j'itère sur les tokens et je construit ma liste de token, // mot clef critère de recherche tokenizer.each { String it -> criteriaList.add(it.toLowerCase()) } //je collect tous les noms de fichier dans le dossier List<String> fileNameList = vracDir .listFiles() .collect { File it -> it.directory ?: it.name } // je collect les noms de fichier qui contiendraient un des criteres List<String> resultList = fileNameList.findAll { String name -> criteriaList.findAll { String crit -> name.toLowerCase().contains(crit) } } // je parcours ma liste de résultat pour les effacer resultList.each { String fileName -> assert new File(vracDir.path + sep + fileName).delete() } println fileNameList.size() println resultList.size() resultList.empty ?: println(vracDir.path + sep + resultList.first())</code></pre> </div> </div> https://cheroliv.com/blog/2019/0004_groovy_replace_string_load_properties_post.html Wed, 17 Jul 2019 00:00:00 +0000 blog/2019/0004_groovy_replace_string_load_properties_post.html <div class="paragraph"> <p>Voici un bout de code fonctionnel en groovy,<br> pour changer toutes les occurrences d’une séquence de caractères dans une String<br> et charger un fichier .properties dans un objet properties.<br> Exécuter une commande dans une String.<br> replaceTextinFile.groovy<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">#!/usr/bin/env groovy println System.getProperty("user.home") static String getSeparator_() { System.getProperty("file.separator") } String separator = separator_ String path = System.getProperty("user.home") .concat("${separator}.gradle" + separator + "gradle.properties") File propertiesFile = new File(path) assert propertiesFile.exists() && !propertiesFile.directory Properties gradleProperties = new Properties() propertiesFile.withInputStream { InputStream it -> gradleProperties.load(it) } String user_name = gradleProperties.getProperty("user_name") String text String resultText text = new File("${System.getProperty("user.home")}" + separator + "src" + separator + "cheroliv.github.io" + separator + "src" + separator + "main" + separator + "resources" + separator + "eco_space.txt").text String to = separator + "media" + separator + "${user_name}" + separator + "320" + separator + "videoCours" + separator String from = "${System.getProperty("user.home")}" + separator + "p2p" + separator resultText = text.replace(to, from) println resultText //execute command line in a string println "rsync -avr ${resultText} ${to}".execute().text</code></pre> </div> </div> https://cheroliv.com/blog/2019/0003_groovy_char_ascci_post.html Wed, 10 Jul 2019 00:00:00 +0000 blog/2019/0003_groovy_char_ascci_post.html <div class="paragraph"> <p>Voici un bout de code fonctionnel en Groovy, qui génère un fichier texte,<br> avec les 256 premiers caractères lisibles du tableau ASCII<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">#!/usr/bin/env groovy import java.nio.charset.StandardCharsets List<Character> chars = new ArrayList<>() int j = 0 Character jumpLine = '\n' 256.times { Integer idx -> if (Character.isAlphabetic(idx) || Character.isDigit(idx)) { if (j % 10 == 0 && j != 0) { chars.add(jumpLine) chars.add(idx as char) } else chars.add(idx as char) j++ } } String seperator = System.getProperty("file.separator") String path = "${System.getProperty("user.home")}${seperator}ascii.txt" File speCharFile = new File(path) if (speCharFile.exists() && !speCharFile.directory) { speCharFile.text = "" } else { speCharFile.createNewFile() } String text = new String() chars.each { Character it -> text = it == jumpLine ? "$text$it" : "$text $it " } speCharFile.setText(text, StandardCharsets.UTF_8.toString())</code></pre> </div> </div> <div class="paragraph"> <p>j’ai nommé le fichier spe_char.groovy,<br> depuis le dossier ou est le fichier<br> ouvrir un terminal et copier coller pour exécuter le script<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ groovy spe_char.groovy</code></pre> </div> </div> <div class="paragraph"> <p>résultat:</p> </div> <div class="paragraph"> <p>0 1 2 3 4 5 6 7 8 9 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z a b c d e f g h i j k l m n o p q r s t u v w x y z ª µ º À Á Â Ã Ä Å Æ Ç È É Ê Ë Ì Í Î Ï Ð Ñ Ò Ó Ô Õ Ö Ø Ù Ú Û Ü Ý Þ ß à á â ã ä å æ ç è é ê ë ì í î ï ð ñ ò ó ô õ ö ø ù ú û ü ý þ ÿ</p> </div>