# Entity App Server 평가 > 작성일: 2026-03-25 > 대상 버전 기준: create-entity-app-server 0.3.x Entity App Server를 아키텍처, 확장성, 운영성, 문서성, 제품화 적합성 관점에서 평가한 문서입니다. --- ## 한줄 평가 Entity Server 기반 업무 시스템을 빠르게 제품화하기에 상당히 실용적인 구조다. 다만 `system.js` 난독화 코어 + `app/` 공개 소스라는 이중 구조 때문에, 장기적으로는 빌드/문서/운영 규칙을 강하게 관리하지 않으면 복잡도가 다시 올라갈 가능성이 있다. --- ## 종합 점수 | 항목 | 평가 | 점수(10) | 메모 | | ---------------- | --------- | -------: | -------------------------------------------------------- | | 아키텍처 명확성 | 좋음 | 8.8 | 코어와 앱 경계가 분명함 | | 확장성 | 매우 좋음 | 9.0 | plugins/routes/hooks/schedules 구조가 실용적임 | | 운영성 | 좋음 | 8.2 | run/update/service 스크립트가 잘 정리됨 | | 문서성 | 좋음 | 8.4 | 핵심 문서는 충분하지만 유지 비용이 큼 | | 디버깅/투명성 | 보통 | 6.8 | 난독화 코어 특성상 내부 추적 한계가 있음 | | 빌드/배포 단순성 | 보통 이상 | 7.4 | 생성 프로젝트는 단순하지만 소스 리포지토리 빌드는 복잡함 | | 제품화 적합성 | 매우 좋음 | 8.9 | 내부 업무 시스템, B2B 백오피스에 특히 적합 | **총평:** 8.4 / 10 --- ## 강점 ### 1. 코어와 커스터마이징 영역이 잘 분리되어 있다 - `system.js`는 서버 코어를 감추고, `app/`은 수정 가능한 비즈니스 영역으로 남긴다. - 이 구조 덕분에 플랫폼 제공자와 앱 개발자의 책임 범위가 명확하다. - `@system/api`를 공개 계약으로 두어 app 코드가 내부 구현에 직접 의존하지 않게 만든 점도 좋다. ### 2. 확장 단위가 실무 친화적이다 - `plugins/`, `routes/`, `hooks/`, `schedules/` 구분이 실제 팀 개발 방식과 잘 맞는다. - 특히 Entity Server 프록시 구조 위에 business route, entity hook, scheduler를 얹는 방식은 업무 시스템 개발에 효율적이다. - 라우트와 훅, 스케줄이 모두 자동 로드되므로 반복 보일러플레이트가 적다. ### 3. Entity Server와의 역할 분담이 현실적이다 - 표준 CRUD, 인증, 파일 같은 공통 기능은 Entity Server에 위임한다. - 앱서버는 조합 로직, 외부 API 연동, 정책, 집계, 후처리에 집중한다. - 이 분리는 과도하게 모든 것을 직접 구현하는 구조보다 유지보수성이 높다. ### 4. 운영 스크립트가 생각보다 잘 갖춰져 있다 - `run.sh`, `update-server.sh`, `service-install.sh`, `entity.sh`가 있어 실제 운영 진입 장벽이 낙다. - 생성 프로젝트 기준으로는 root의 `system.js`만 중심으로 실행되게 정리되어 배포 모델도 단순하다. ### 5. 문서 방향이 코드 구조와 잘 맞는다 - `architecture.md`, `system.md`, `system-api.md`, `scripts-guide.md`처럼 문서 역할이 비교적 분리되어 있다. - 다른 개발자가 처음 들어와도 “어디를 수정해야 하는지”를 빠르게 이해할 수 있다. --- ## 약점과 리스크 ### 1. 난독화 코어는 플랫폼 보호에는 유리하지만 디버깅에는 불리하다 - `system.js`가 감춰져 있기 때문에 app 영역 밖에서 문제가 생기면 추적 범위가 제한된다. - 플랫폼 제공자에게는 장점이지만, 사용하는 팀 입장에서는 내부 동작을 완전히 검증하기 어렵다. - 따라서 공개 API 안정성과 문서 품질이 구조적으로 매우 중요해진다. ### 2. 소스 리포지토리와 생성 프로젝트의 실행 모델이 다르다 - 소스 리포지토리는 `dist/`를 배포 산출물과 템플릿 원본으로 함께 다루고, 생성된 프로젝트는 root `system.js`를 직접 실행한다. - 이 차이는 합리적이지만, 문서와 스크립트가 조금만 어긋나도 혼동이 생긴다. - 즉 제품 자체는 단순한데, 플랫폼을 만드는 저장소는 단순하지 않다. ### 3. 문서와 템플릿 복제 비용이 높다 - source 문서와 `dist/` 산출물이 함께 존재하므로, 이름 변경이나 정책 변경이 문서와 빌드 규칙에 동시에 반영되어야 한다. - 최근의 명칭 정리처럼 용어 변경이 생길 때 누락 가능성이 구조적으로 존재한다. ### 4. 빌드 파이프라인은 기능이 많아질수록 민감해질 수 있다 - `deploy`, `minify`, `config.example.json` 치환, dist/template 복사 규칙 등이 많다. - 이런 시스템은 유연하지만, 규칙을 이해하지 못한 상태에서 기능을 추가하면 빌드/배포 결과가 예상과 달라질 수 있다. ### 5. 테스트 전략은 아직 더 강화될 여지가 있다 - 현재 구조는 문서와 스크립트가 강한 편이지만, 자동 검증 범위가 더 넓어지면 플랫폼 신뢰도가 올라간다. - 특히 생성 템플릿이 실제로 항상 실행 가능한지 검증하는 smoke test가 중요하다. --- ## 어떤 팀에 잘 맞는가 ### 잘 맞는 경우 - Entity Server를 이미 표준 백엔드 코어로 쓰고 있는 팀 - 빠르게 업무용 API 서버를 늘려야 하는 팀 - 결제, OCR, LLM, 알림, 본인인증 같은 외부 서비스 연동이 많은 팀 - 백오피스, B2B, 운영도구, 고객사별 커스터마이징 프로젝트 ### 덜 맞는 경우 - 프레임워크 내부까지 모두 투명하게 통제하고 싶은 팀 - 오픈소스 생태계처럼 코어 내부 변경과 외부 기여를 활발히 받을 프로젝트 - 초저지연을 최우선으로 하는 서비스 - 빌드/배포 규칙보다 단일 바이너리나 단순 런타임을 더 선호하는 팀 --- ## 추천 개선 우선순위 ### 우선순위 A 1. 생성 프로젝트 smoke test 자동화 2. source repo와 template 간 문서/스크립트 동기화 자동 검사 3. build 결과에 대한 최소 검증 체크리스트 자동화 ### 우선순위 B 1. `dist/` 단일 산출물 기준으로 create/update 경로를 계속 단순화 2. 운영 파일명, 로그 파일명, 버전 파일명 규칙을 문서 한 곳에 모으기 3. plugin/route/schedule의 빌드 제어 규칙을 문서화한 표를 별도 제공 ### 우선순위 C 1. 코어 공개 API 변경 이력 문서화 2. 예제 프로젝트 추가 3. 템플릿 생성 직후 실행되는 진단 스크립트 제공 --- ## 결론 Entity App Server는 “범용 프레임워크”라기보다 “Entity Server 생태계 위에서 실무용 앱 서버를 빠르게 만드는 제품형 플랫폼”으로 평가하는 편이 정확하다. 이 관점에서는 상당히 잘 설계되어 있다. - 코어 보호 - 실무 친화적 확장 구조 - 운영 스크립트 제공 - 문서 기반 온보딩 이 네 가지가 잘 맞물린다. 반대로 장기 리스크는 대부분 같은 지점에서 나온다. - 코어가 감춰져 있으므로 문서와 공개 API 품질이 매우 중요함 - source repo와 생성 프로젝트의 차이를 지속적으로 관리해야 함 - 템플릿/배포 산출물 복제가 많아질수록 동기화 비용이 커짐 따라서 현재 평가는 다음과 같다. > **업무 시스템용 플랫폼으로는 매우 유용하다.** > **다만 플랫폼 저장소 자체는 문서, 빌드, 템플릿 동기화를 꾸준히 관리해야 품질이 유지된다.**