# 워드프레스 코드 리팩토링 기법 6가지

URL: https://noonwp.com/ko/journal/code-refactoring-techniques-wordpress-ko
Type: blog
Locale: ko
Published: 2026-06-29
Updated: 2026-07-04

---

> 워드프레스 개발자를 위한 실전 코드 리팩토링 기법. Extract Method, 가드 클로즈, DRY 원칙, FSE 템플릿 파츠, theme.json 토큰까지 실제 제작 현장의 제약과 함께 다룹니다.

코드 리팩토링 기법 여섯 가지가 워드프레스 코드베이스의 운명을 가릅니다. 1년 차를 넘기고도 유지보수가 가능한 상태로 남을지, 아니면 새로 들어온 프리랜서가 두려움 속에 물려받는 functions.php가 될지가 여기서 결정됩니다. 이 폴리오는 블록 테마 개발과 플러그인 PHP에 실제로 통하는 기법만 다룹니다.

![노트북 화면에 깔끔한 함수 구조로 정리된 PHP 코드](https://fdzlnqpwsaniezitwiuw.supabase.co/storage/v1/object/public/cms-media/noonwp/2026-06/54ffc6-inline1.webp)

## 리팩토링 시점을 알려주는 코드 냄새

400줄을 넘긴 functions.php는 믿을 만한 신호입니다. 석 달 전 "임시로" 복제해 둔 블록 패턴이 지금은 클라이언트 테마 디렉터리 여기저기에 조금씩 다른 버전 다섯 개로 존재하는 것도 마찬가지입니다. 코드 냄새는 버그가 아닙니다. 사이트는 잘 돌아갑니다. 클라이언트도 만족합니다. 하지만 다음에 이 코드베이스를 만질 개발자는 40분이면 될 일을 이해하는 데 네 시간을 쓰게 됩니다.

실전에서 확인한 바로는, 리팩토링을 미룰수록 비용은 가파르게 오릅니다. 2024년 Stack Overflow 설문에 따르면 개발자의 62%가 기술 부채를 매일 겪는 최대 좌절 요인으로 꼽았습니다. 워드프레스 프로젝트에서는 보통 템플릿 함수 안에 조건문이 4단계로 중첩되어 있거나, register_block_pattern() 호출이 소유권 없이 서로 다른 세 파일에 흩어진 형태로 나타납니다.

어떤 기법을 쓰든 전제 조건은 하나, 테스트 커버리지입니다. 테스트 없는 리팩토링은 리팩토링이 아니라 낙관에 기댄 재작성일 뿐입니다. 워드프레스라면 WP-CLI와 PHPUnit이 기본 토대가 됩니다. PHP 코드가 거의 없는 FSE 전용 블록 테마에서는 로컬 Lando나 LocalWP 환경에 대한 Playwright 엔드투엔드 검사가 같은 역할을 합니다.

## Extract Method: 작업대 위 첫 번째 도구

워드프레스 PHP 개발에서 가장 널리 통하는 리팩토링 기법은 Extract Method입니다. 원칙은 단순합니다. 함수 하나가 두 가지 이상의 일을 한다면 쪼갭니다.

플러그인의 파일 업로드 핸들러를 예로 들어봅시다. 원래 구현은 MIME 타입을 검증하고, 파일 크기를 확인하고, S3 ACL을 결정하고, 첨부파일 메타데이터를 기록하는 일을 순서대로 처리하는 200줄짜리 함수입니다. 리팩토링한 버전은 is_valid_mime_type(), is_within_size_limit(), get_s3_acl(), write_attachment_meta() 네 개의 메서드로 나뉩니다. 바깥쪽 함수는 마치 주석이 달린 산문처럼 읽힙니다.

구텐베르크 블록 테마에서도 같은 원칙이 functions.php에 적용됩니다. 블록 스타일을 등록하고, 에디터 스크립트를 큐에 넣고, 블록 서포트를 설정하고, 커스텀 쿼리 변수까지 하나의 after_setup_theme 훅 안에서 처리하는 테마는 한 번에 너무 많은 일을 하는 셈입니다. 이를 이름이 붙은 개별 함수로 나누고 /inc/ 디렉터리에서 include하는 일은 거창한 아키텍처가 아닙니다. 한 시간이면 파악할 수 있는 코드베이스와, 가이드 투어가 필요한 코드베이스의 차이일 뿐입니다.

마진에 적어두자면, 이 접근은 블록 훅 API가 격리에 유리한 등록 패턴을 추가로 제공하는 워드프레스 6.4 이상에서 잘 통합니다.

## 가드 클로즈로 중첩 조건문 정리하기

중첩 조건문은 실무에서 검토한 워드프레스 PHP 코드 중 두 번째로 흔한 골칫거리입니다. 플러그인 개발에서 자주 보이는 패턴은 이렇습니다. 함수가 권한을 확인하고, 그다음 포스트 타입이 맞는지 확인하고, 그다음 메타 값을 검증한 뒤에야 실제 로직을 실행합니다. 각 조건이 이전 조건 안에 중첩되면서 계단 모양의 코드가 만들어집니다.

가드 클로즈는 이 구조를 뒤집습니다. 실행을 막아야 할 각 조건을 함수 맨 위의 이른 반환(early return)으로 바꿉니다. 성공 경로는 함수 맨 아래, 들여쓰기 없이, 중괄호 깊이를 따라가지 않아도 읽히는 형태로 남습니다.

`// Before: 계단식 재앙
function handle_submission( $post_id ) {
    if ( current_user_can( 'edit_posts' ) ) {
        if ( get_post_type( $post_id ) === 'project' ) {
            if ( get_post_meta( $post_id, '_status', true ) === 'pending' ) {
                // 실제 로직은 여기
            }
        }
    }
}

// After: 가드 클로즈
function handle_submission( $post_id ) {
    if ( ! current_user_can( 'edit_posts' ) ) return;
    if ( get_post_type( $post_id ) !== 'project' ) return;
    if ( get_post_meta( $post_id, '_status', true ) !== 'pending' ) return;

    // 실제 로직은 여기
}`리팩토링한 버전은 더 짧을 뿐 아니라, 무엇보다 각 조건을 독립적으로 읽고 이해하고 수정할 수 있습니다. 비즈니스 로직이 바뀔 때, 그리고 반드시 바뀝니다, 수정은 외과적으로 정확해집니다.

![포스트잇 보드에 모듈형 구조로 코드 아키텍처를 설계하는 개발자](https://fdzlnqpwsaniezitwiuw.supabase.co/storage/v1/object/public/cms-media/noonwp/2026-06/406483-inline2.webp)

## 블록 패턴의 DRY 원칙: 템플릿 중복을 멈추다

DRY, 같은 것을 반복하지 않는다는 원칙은 블록 테마 개발에서 가장 자주 깨지는 리팩토링 원칙입니다. 워드프레스 프리랜서가 클라이언트 사이트를 만들 때 초기 패턴 라이브러리는 대개 유기적으로 늘어납니다. 여기 하나의 히어로 블록, 저기 하나의 후기 섹션. 본격적인 개발 3개월 차쯤 되면 마크업이 80% 동일한 히어로 블록 변형이 다섯 개씩 존재하는 일이 흔합니다.

이럴 때의 리팩토링 접근은 공통 구조를 찾아내 하나의 표준 패턴으로 추출한 뒤, 시각적 차이는 블록 패턴 변형이나 글로벌 스타일로 처리하는 것입니다. [Create Block Theme 플러그인](https://wordpress.org/plugins/create-block-theme/)이 도구 차원에서 지원하는 부분이 바로 이것입니다. "개발 중인 테마"와 "내보내기 가능한 재사용 테마" 사이의 간극을 명시적으로 드러내 줍니다.

플러그인 PHP에서는 공통 메서드를 부모 클래스로 추상화하는 것이 대응 기법입니다. 두 개의 애드온 클래스가 같은 옵션 키를 읽는 set_settings() 메서드를 각각 정의하고 있다면, 그 메서드는 공유 추상 클래스에 있어야 합니다. 옵션 키가 바뀌면 수정은 한 번으로 끝납니다.

이 리팩토링을 건너뛰어도 되는 경우가 있습니다. 중복된 패턴이 실제로 서로 다른 편집 맥락에서 독립적으로 진화할 것이라면 그렇습니다. 억지로 적용한 DRY는 원래의 중복보다 더 나쁜 결합을 만듭니다. 판단 기준은 두 중복 코드가 논리적으로 함께 바뀔지 여부입니다. 그렇다면 추출하고, 아니라면 그대로 두십시오.

## FSE 템플릿 리팩토링: 모놀리스에서 템플릿 파츠로

풀 사이트 에디팅 템플릿 시스템은 많은 블록 테마 개발자가 아직 충분히 활용하지 못하는 구조적 리팩토링 기회를 열어주었습니다. 헤더 전체 마크업, 내비게이션, 콘텐츠 영역, 사이드바, 푸터를 한 파일에 담은 templates/single.html은 모놀리식 함수의 FSE판입니다. 동작은 합니다. 다만 포스트 타입이 열두 개인 사이트에서 유지보수하기란 불가능에 가깝습니다.

리팩토링 경로는 템플릿 파츠입니다. 헤더는 parts/header.html로, 푸터는 parts/footer.html로 옮기고, 필요한 각 템플릿에서 `<!-- wp:template-part {"slug":"header"} /-->`로 참조합니다. 클라이언트가 내비게이션 구조를 바꾸면, 수정은 파일 하나에서 일어나고 모든 곳에 전파됩니다.

가정이 아닙니다. 구텐베르크 이슈 트래커에는 코어 팀이 진행 중인 템플릿 리팩토링 스레드가 있으며, 같은 패턴이 더 큰 규모에서도 반복되고 있음을 보여줍니다.

템플릿을 리팩토링하지 말아야 할 때에 대한 현장 메모 하나. 사이트에 서로 조금씩 다른 템플릿이 열 개 있고 클라이언트가 사이트 에디터에서 직접 자주 수정한다면, 템플릿 파츠로의 공격적인 추출은 오히려 혼란을 만들 수 있습니다. 사이트 에디터의 템플릿 파츠 UI는 나아지고 있지만 발견 가능성 면에서는 여전히 마찰이 있습니다. 비기술 클라이언트라면 아키텍처적으로 덜 우아하더라도 움직이는 부품을 줄이는 쪽이 옳은 선택일 때가 많습니다.

## 함수형 PHP 메서드로 반복문 정리하기

PHP 내장 배열 함수, array_map, array_filter, array_reduce는 워드프레스 플러그인 코드에서 충분히 활용되지 못하고 있습니다. 명시적인 foreach 반복문과 중간 변수를 없애고, 메커니즘이 아니라 의도를 드러내는 코드를 만들어 줍니다.

워드프레스에서 흔한 패턴은 포스트 객체 배열을 순회하며 계산된 값을 뽑아내고, 반복문 안에서 누산기를 만드는 방식입니다. 함수형으로 대응하면 각 포스트를 변환할 때는 array_map을, 최종 값을 계산할 때는 array_reduce를 씁니다. 결과는 줄 수가 줄어들 뿐 아니라, 무엇보다 반복문 안에 가변 상태가 사라진다는 점입니다.

이 기법은 연산이 순수하게 변환이나 축약일 때 적합합니다. 항목마다 에러 처리가 필요한 부수 효과, 데이터베이스 기록이나 API 호출이 있는 연산에는 맞지 않습니다. 그런 경우에는 에러 경계가 명확한 명시적 반복문이 옳은 선택입니다.

![코드 리팩토링 후 자동화 테스트 결과를 화면에서 검토하는 개발자](https://fdzlnqpwsaniezitwiuw.supabase.co/storage/v1/object/public/cms-media/noonwp/2026-06/5ef3dc-inline3.webp)

## theme.json으로 디자인 토큰 리팩토링하기

여섯 번째 기법은 블록 테마 개발에 특화된 것으로, 다른 종류의 리팩토링입니다. CSS와 PHP에 하드코딩된 값을 theme.json 안의 이름 붙은 디자인 토큰으로 옮기는 작업입니다.

여섯 개의 서로 다른 CSS 규칙에서 color: #1a1a2e를 정의하거나, style.css와 에디터 스타일시트 양쪽에 같은 폰트 스택을 하드코딩한 테마는 유지보수 문제를 안고 있습니다. 브랜드 색상이 바뀌면 개발자는 헥스 값을 검색해야 하고, 폰트가 바뀌면 두 곳 이상에서 바뀌게 됩니다.

theme.json은 디자인 결정을 명시적으로 이름 붙여 이 문제를 해결합니다. 컬러 팔레트 항목 "slug": "primary"는 CSS에서 var(--wp--preset--color--primary)가 됩니다. theme.json에서 헥스 값을 바꾸면, 프리셋 색상을 쓰는 모든 블록이 프런트엔드와 사이트 에디터 양쪽에서 자동으로 업데이트됩니다.

같은 원칙이 여백 스케일, 폰트 크기, 커스텀 레이아웃 치수에도 적용됩니다. theme.json 토큰을 일관되게 쓰도록 테마를 리팩토링하는 일은 화려하지 않습니다. 시간이 걸립니다. 실전에서 확인한 바로는, 이 작업을 마친 사이트에서는 다음 디자인 반복 작업이 눈에 띄게 빨라지고, 에디터와 프런트엔드 사이의 스타일 드리프트가 크게 줄어듭니다.

## 리팩토링이 오히려 해가 될 때

이 글의 콜로폰은 이렇습니다. 모든 코드베이스가 공격적인 리팩토링으로 득을 보는 것은 아닙니다. 자제를 권하는 세 가지 상황이 있습니다.

첫째, 2주 뒤 납품 마감이 있는 클라이언트 사이트입니다. 리팩토링은 위험을 끌어들입니다. 기능을 출시하고, 부채를 문서화하고, 정리 작업은 일정에 넣으십시오.

둘째, 아직 완전히 이해하지 못한 코드입니다. 리팩토링에는 그 코드가 무엇을 하는지에 대한 모델이 필요합니다. 그 모델이 불완전하면, 리팩토링된 버전이 우연한 것처럼 보였지만 실제로는 하중을 지탱하던 동작을 없애버릴 수 있습니다.

셋째, 6개월 안에 완전히 교체될 코드입니다. 맥킨지의 2024년 데이터는 체계적인 리팩토링이 임기응변식 접근보다 40에서 50퍼센트 더 빠르게 완료된다는 것을 보여줍니다. 다만 이 이점은 리팩토링된 코드가 계속 유지보수된다는 전제 위에 있습니다. 코드가 임시적이라면 그 투자는 복리로 돌아오지 않습니다.

어떤 워드프레스 코드베이스든 리팩토링에 앞서 던져야 할 질문은 이렇습니다. 지금 이 코드가 무엇을 하는지 한 문장으로 말할 수 있습니까? 아니라면, 다시 쓰기 전에 먼저 읽으십시오.

## FAQ

### 워드프레스 개발에서 코드 리팩토링이란 무엇인가요?

코드 리팩토링은 기존 PHP 함수, 블록 패턴, FSE 템플릿을 동작은 그대로 둔 채 더 읽기 쉽고 유지보수하기 좋은 구조로 재구성하는 일을 말합니다. 기능을 추가하거나 버그를 고치는 작업이 아니라, 프로젝트 수명 주기 내내 유지보수하기 쉬운 더 깔끔한 구조를 만드는 것이 목표입니다.

### 블록 테마의 functions.php도 리팩토링해야 하나요?

functions.php가 200에서 300줄을 넘겼다면 그렇습니다. 권장 방식은 /inc/ 디렉터리 안에 관심사별로 파일을 나누는 것입니다. 블록 스타일 등록, 에디터 스크립트, 블록 서포트, 커스텀 포스트 타입을 각각 하나씩 담당하게 하고 functions.php에서 include 하십시오. 그러면 탐색과 테스트가 훨씬 쉬워집니다.

### Extract Method 리팩토링 기법이란 무엇인가요?

Extract Method는 여러 가지 일을 하는 함수를 각각 한 가지 일만 하는 이름이 붙은 더 작은 함수들로 나누는 기법입니다. 워드프레스 PHP에서 흔한 예는 입력을 검증하고, 데이터를 처리하고, 데이터베이스에 기록하는 큰 플러그인 함수를 세 개의 독립된 메서드로 나누는 것입니다. 각 메서드는 그 자체로 읽고 테스트할 수 있게 됩니다.

### PHP의 가드 클로즈란 무엇인가요?

가드 클로즈는 실행을 막아야 할 조건을 처리하기 위해 함수 맨 위에 두는 이른 반환 구문입니다. if-else 블록 안에 로직을 중첩하는 대신, 조건이 충족되지 않으면 곧바로 반환합니다. 이를 통해 워드프레스 플러그인 코드에서 흔한 계단식 중첩 패턴이 사라지고, 성공 실행 경로가 훨씬 읽기 쉬워집니다.

### FSE 테마에서 theme.json은 코드 리팩토링에 어떻게 도움이 되나요?

theme.json은 색상, 폰트 크기, 여백 같은 디자인 토큰을 이름으로 한 번만 정의하게 해줍니다. CSS와 블록 마크업은 CSS 커스텀 프로퍼티를 통해 이 토큰을 참조합니다. 디자인 값이 바뀌면 theme.json 한 곳만 수정하면 됩니다. 여러 CSS 파일에 흩어진 하드코딩된 헥스 값이라는, 오래된 워드프레스 테마에서 흔한 유지보수 문제가 사라집니다.

### 워드프레스 코드를 리팩토링하지 말아야 할 때는 언제인가요?

자제가 필요한 상황은 세 가지입니다. 납품 마감이 임박해 리팩토링이 위험을 끌어들일 때, 코드가 무엇을 하는지 아직 명확한 모델이 없을 때, 그리고 코드가 짧은 기간 안에 완전히 교체될 때입니다. 다시 쓰기 전에 먼저 읽어야 합니다. 리팩토링은 이후에도 그 코드가 계속 유지보수될 때만 이익을 내는 투자입니다.

### FSE의 템플릿 파츠는 리팩토링과 어떤 관계가 있나요?

풀 사이트 에디팅의 템플릿 파츠는 PHP로 치면 Extract Method에 해당하는 FSE 버전입니다. 헤더, 푸터, 콘텐츠 마크업을 담은 하나의 큰 템플릿 파일 대신, 반복되는 각 구간을 이름이 붙은 템플릿 파츠로 추출합니다. 예를 들어 헤더를 바꾸면 그 변경은 여러 파일을 일일이 수정하지 않고도 해당 템플릿 파츠를 참조하는 모든 템플릿에 전파됩니다.