Dart 튜토리얼 18편: 패키지 제작과 구조(dart create·lib/src·package layout·패키지 페이지)

Why#

NOTE

패키지의 최소 구조(예: pubspec.yaml, lib/)를 수동으로 만들면 빠르게 누락이 생길 수 있습니다.
초기 구조는 템플릿을 쓰는 흐름이 제시됩니다.

What#

NOTE

패키지 템플릿으로 새 패키지를 만들 때는 dart create에 -t package를 사용합니다.

How#

TIP

패키지 생성 명령은 다음과 같습니다.

1
$ dart create -t package <PACKAGE_NAME>

Watch out#

WARNING

패키지 생성 이후에도 “공개 API 경계”와 “문서/예제”는 직접 정리해야 합니다.
즉, 템플릿은 시작일 뿐이며, 구조를 의도대로 다듬는 단계가 필요합니다.

결론: 패키지는 템플릿으로 시작하고, 바로 “공개 API 경계” 설계로 넘어갑니다.

Why#

NOTE

구현 코드가 외부에 직접 노출되면, 사용자가 구현 세부에 의존하게 됩니다.
그 상태에서 리팩터링을 하면, 사용자 코드가 깨지기 쉬워집니다.

What#

NOTE

lib/는 다른 패키지가 import할 수 있는 공개 라이브러리 위치로 설명됩니다.
반면 lib/src/ 아래 구현 코드는 “사적인 구현”으로 취급되며, 외부에서 import할 필요가 없다고 설명됩니다.

How#

TIP

공개 API는 lib/<package>.dart 같은 “메인 라이브러리 파일”에서 export로 모아서 제공하는 방식이 제시됩니다.
또한 show로 export할 심볼을 제한해, 공개 표면을 명확히 할 수 있습니다.

1
export 'src/cascade.dart' show Cascade;
2
export 'src/handler.dart' show Handler;
3
export 'src/hijack_exception.dart' show HijackException;
4
export 'src/middleware.dart' show Middleware, createMiddleware;
5
export 'src/middleware/add_chunked_encoding.dart' show addChunkedEncoding;
6
export 'src/middleware/logger.dart' show logRequests;
7
export 'src/middleware_extensions.dart' show MiddlewareExtensions;
8
export 'src/pipeline.dart' show Pipeline;
9
export 'src/request.dart' show Request;
10
export 'src/response.dart' show Response;
11
export 'src/server.dart' show Server;
12
export 'src/server_handler.dart' show ServerHandler;

Watch out#

WARNING

part⁵ 지시문이 언급되지만, 일반적인 코드 분할 목적이라면 “작은 라이브러리(미니 라이브러리)”로 나누는 방향이 권장되는 것으로 설명됩니다.
즉, 여러 파일을 한 라이브러리로 묶는 방식은 신중하게 선택해야 합니다.

결론: 공개 API는 lib/, 구현은 lib/src/로 분리하고, export로 공개 표면을 의도대로 구성합니다.

Why#

NOTE

패키지 사용자는 코드를 열어보기 전에 README부터 봅니다.
업그레이드할 때는 CHANGELOG를 보고 “무엇이 바뀌었는지”를 판단합니다.

What#

NOTE

README.md는 패키지 페이지에 렌더링되어 표시된다고 설명됩니다.
CHANGELOG.md는 릴리즈별 섹션과 버전 헤딩 형식이 제시됩니다.

How#

TIP

CHANGELOG.md 예시는 다음 형식이 제시됩니다.

1
# 1.0.1
2

3
* Fixed missing exclamation mark in `sayHi()` method.
4

5
# 1.0.0
6

7
* **Breaking change:** Removed deprecated `sayHello()` method.
8
* Initial stable release.
9

10
## Upgrading from 0.1.x
11

12
Change all calls to `sayHello()` to instead be to `sayHi()`.
13

14
# 0.1.1
15

16
* Deprecated the `sayHello()` method; use `sayHi()` instead.
17

18
# 0.1.0
19

20
* Initial development release.

Watch out#

WARNING

CHANGELOG는 도구가 파싱할 수 있도록 “버전마다 섹션/일관된 헤딩 레벨/버전 번호 포함” 같은 규칙이 제시됩니다.
즉, 형식을 제각각으로 쓰면 자동화 도구와 호환성이 떨어질 수 있습니다.

결론: README/CHANGELOG는 패키지의 “사용법/변경 이력”을 전달하는 핵심 파일이므로, 형식부터 맞춥니다.

Why#

NOTE

사용자는 패키지 페이지에서 “바로 복사해서 실행”할 수 있는 예시를 원합니다.
예시가 없거나 읽기 어렵다면, 사용자는 패키지를 떠나기 쉽습니다.

What#

NOTE

README에 “Get started/Usage” 섹션과 이해하기 쉬운 코드 샘플을 넣는 팁이 제시됩니다.
또한 코드 블록은 ```dart 형태로 Dart 문법 강조를 적용하는 팁이 제시됩니다.

How#

TIP

다음처럼 코드 블록에 dart를 지정하면 Dart 문법 강조가 적용됩니다.

1
final like = 'this';

Watch out#

WARNING

예제 코드는 “작고 복사 가능한 단위”가 기본이며, 더 큰 예시는 example/ 디렉터리에 두는 흐름이 언급됩니다.
즉, README에 모든 것을 넣기보다는 “페이지 + 예제 디렉터리”로 역할을 분리하는 편이 좋습니다.

결론: 패키지 페이지는 “복사 가능한 최소 예시 + 올바른 코드 블록(````dart`)“을 기본으로 구성합니다.