規範の構造: 組織と規約
適切に組織化されたコード構造は、保守可能なプロジェクトの基礎です。 Claude は、規則の定義、フォルダーの整理、メンテナンスを支援します。 関心事の分離 開発全体を通して一貫して。
この記事では、プロジェクトを組織するためのベスト プラクティスについて説明します。 スプリングブーツ e 角度のある命名規則に重点を置き、 構成管理とコード編成パターン。
何を学ぶか
- スケーラブルなプロジェクトのためのフォルダー構成
- ファイル、クラス、変数の命名規則
- 懸念事項の効果的な分離
- 複数環境の構成管理
- 共有コードのパターン
組織理念
コード構造の 5 つの原則
| 原理 | 説明 | 利点 |
|---|---|---|
| コロケーション | 近くの関連ファイル | 高速なナビゲーション、少ないコンテキスト切り替え |
| 予測可能性 | 一貫した構造 | 迅速なオンボーディング、エラーの減少 |
| モジュール性 | 分離されたフィーチャ | 再利用性、独立したテスト |
| スケーラビリティ | リファクタリングなしで成長する | 長期メンテナンス |
| 明示性 | わかりやすい名前 | 自己文書化されたコード |
バックエンド構造: Spring Boot
機能ごとのパッケージとレイヤーごとのパッケージ
レイヤーごとのパッケージ化
com.company.app/
├── controller/
│ ├── OrderController
│ ├── ProductController
│ └── CustomerController
├── service/
│ ├── OrderService
│ ├── ProductService
│ └── CustomerService
├── repository/
│ ├── OrderRepository
│ └── ProductRepository
└── model/
├── Order
└── Product長所: シンプルで親しみやすい
に対して： 結合度が高く、ナビゲートが難しい
機能ごとのパッケージ
com.company.app/
├── order/
│ ├── OrderController
│ ├── OrderService
│ ├── OrderRepository
│ └── Order
├── product/
│ ├── ProductController
│ ├── ProductService
│ └── Product
└── shared/
└── ...長所: 凝集性が高く、操作が簡単
に対して： 規律が必要です
おすすめ
個人プロジェクトや小規模チームの場合、 機能ごとのパッケージ それが好ましいです。 関連するコードをまとめて保持し、将来のマイクロサービスでのリファクタリングを容易にします。
完全なスプリングブーツ構造
Spring Boot プロジェクトの構造
order-service/
├── src/
│ ├── main/
│ │ ├── java/com/company/orders/
│ │ │ ├── OrderServiceApplication.java
│ │ │ │
│ │ │ ├── order/ # Feature: Orders
│ │ │ │ ├── api/ # Web layer
│ │ │ │ │ ├── OrderController.java
│ │ │ │ │ ├── OrderMapper.java
│ │ │ │ │ └── dto/
│ │ │ │ │ ├── CreateOrderRequest.java
│ │ │ │ │ ├── OrderResponse.java
│ │ │ │ │ └── OrderItemDto.java
│ │ │ │ ├── domain/ # Business logic
│ │ │ │ │ ├── Order.java
│ │ │ │ │ ├── OrderItem.java
│ │ │ │ │ ├── OrderStatus.java
│ │ │ │ │ └── OrderService.java
│ │ │ │ ├── persistence/ # Data access
│ │ │ │ │ ├── OrderRepository.java
│ │ │ │ │ ├── OrderEntity.java
│ │ │ │ │ └── OrderJpaMapper.java
│ │ │ │ └── event/ # Domain events
│ │ │ │ ├── OrderCreatedEvent.java
│ │ │ │ └── OrderEventPublisher.java
│ │ │ │
│ │ │ ├── payment/ # Feature: Payments
│ │ │ │ ├── api/
│ │ │ │ ├── domain/
│ │ │ │ └── client/ # External integration
│ │ │ │ ├── StripeClient.java
│ │ │ │ └── StripeConfig.java
│ │ │ │
│ │ │ ├── shared/ # Cross-cutting
│ │ │ │ ├── exception/
│ │ │ │ │ ├── BusinessException.java
│ │ │ │ │ ├── NotFoundException.java
│ │ │ │ │ └── GlobalExceptionHandler.java
│ │ │ │ ├── validation/
│ │ │ │ │ └── ValidOrderStatus.java
│ │ │ │ └── util/
│ │ │ │ └── DateUtils.java
│ │ │ │
│ │ │ └── config/ # Configuration
│ │ │ ├── SecurityConfig.java
│ │ │ ├── WebConfig.java
│ │ │ ├── KafkaConfig.java
│ │ │ └── properties/
│ │ │ └── AppProperties.java
│ │ │
│ │ └── resources/
│ │ ├── application.yml
│ │ ├── application-dev.yml
│ │ ├── application-prod.yml
│ │ └── db/migration/ # Flyway
│ │ ├── V1__create_orders.sql
│ │ └── V2__add_payment_ref.sql
│ │
│ └── test/
│ └── java/com/company/orders/
│ ├── order/
│ │ ├── api/
│ │ │ └── OrderControllerTest.java
│ │ └── domain/
│ │ └── OrderServiceTest.java
│ └── integration/
│ └── OrderIntegrationTest.java
│
├── docker/
│ └── Dockerfile
├── pom.xml
└── README.md命名規則 Java
Spring Boot の命名規則
## CLASSI
# Controllers: {{ '{' }}Entity{{ '}' }}Controller
OrderController, ProductController, CustomerController
# Services: {{ '{' }}Entity{{ '}' }}Service o {{ '{' }}UseCase{{ '}' }}Service
OrderService, PaymentProcessingService, NotificationService
# Repositories: {{ '{' }}Entity{{ '}' }}Repository
OrderRepository, CustomerRepository
# DTOs: {{ '{' }}Action{{ '}' }}{{ '{' }}Entity{{ '}' }}Request/Response
CreateOrderRequest, OrderResponse, UpdateOrderRequest
# Entities: {{ '{' }}Entity{{ '}' }} o {{ '{' }}Entity{{ '}' }}Entity (per evitare conflitti)
Order, OrderEntity (se c'è domain model separato)
# Exceptions: {{ '{' }}Causa{{ '}' }}Exception
OrderNotFoundException, PaymentFailedException, ValidationException
# Events: {{ '{' }}Entity{{ '}' }}{{ '{' }}Action{{ '}' }}Event
OrderCreatedEvent, PaymentProcessedEvent, OrderShippedEvent
## METODI
# Controller: verbo HTTP implicito nel mapping
@PostMapping → create(...)
@GetMapping("/{id}") → getById(...)
@GetMapping → getAll(...)
@PutMapping → update(...)
@DeleteMapping → delete(...)
# Service: verbo esplicito
createOrder(), findOrderById(), updateOrderStatus(), cancelOrder()
# Repository: Spring Data naming
findById(), findByStatus(), findByCustomerIdAndStatus()
## VARIABILI
# Collections: plurale
List<Order> orders, Set<String> tags
# Singoli: singolare
Order order, Customer customer
# Booleani: is/has/can prefix
boolean isActive, boolean hasPayment, boolean canCancelフロントエンド構造: Angular
スケーラブルなAngularフレームワーク
src/
├── app/
│ ├── core/ # Singleton, app-wide
│ │ ├── services/
│ │ │ ├── api.service.ts
│ │ │ ├── auth.service.ts
│ │ │ ├── storage.service.ts
│ │ │ └── index.ts # Barrel export
│ │ ├── interceptors/
│ │ │ ├── auth.interceptor.ts
│ │ │ ├── error.interceptor.ts
│ │ │ └── loading.interceptor.ts
│ │ ├── guards/
│ │ │ ├── auth.guard.ts
│ │ │ └── role.guard.ts
│ │ └── models/
│ │ ├── user.model.ts
│ │ └── api-response.model.ts
│ │
│ ├── shared/ # Riutilizzabili
│ │ ├── components/
│ │ │ ├── button/
│ │ │ │ ├── button.component.ts
│ │ │ │ ├── button.component.html
│ │ │ │ ├── button.component.css
│ │ │ │ └── button.component.spec.ts
│ │ │ ├── modal/
│ │ │ ├── table/
│ │ │ ├── form-field/
│ │ │ └── index.ts
│ │ ├── pipes/
│ │ │ ├── currency-format.pipe.ts
│ │ │ └── date-ago.pipe.ts
│ │ ├── directives/
│ │ │ └── click-outside.directive.ts
│ │ └── utils/
│ │ └── validators.ts
│ │
│ ├── features/ # Feature modules
│ │ ├── orders/
│ │ │ ├── components/
│ │ │ │ ├── order-list/
│ │ │ │ │ ├── order-list.component.ts
│ │ │ │ │ └── order-list.component.html
│ │ │ │ ├── order-detail/
│ │ │ │ ├── order-form/
│ │ │ │ └── order-card/ # Dumb component
│ │ │ ├── pages/ # Route components
│ │ │ │ ├── orders-page/
│ │ │ │ └── order-detail-page/
│ │ │ ├── services/
│ │ │ │ └── order.service.ts
│ │ │ ├── models/
│ │ │ │ ├── order.model.ts
│ │ │ │ └── order-status.enum.ts
│ │ │ └── orders.routes.ts
│ │ │
│ │ ├── products/
│ │ ├── customers/
│ │ └── dashboard/
│ │
│ ├── layouts/
│ │ ├── main-layout/
│ │ │ ├── main-layout.component.ts
│ │ │ ├── header/
│ │ │ ├── sidebar/
│ │ │ └── footer/
│ │ └── auth-layout/
│ │
│ ├── app.component.ts
│ ├── app.config.ts
│ └── app.routes.ts
│
├── assets/
│ ├── images/
│ ├── icons/
│ └── i18n/ # Traduzioni
│
├── environments/
│ ├── environment.ts
│ └── environment.prod.ts
│
└── styles/
├── _variables.css
├── _mixins.css
└── global.cssAngular の命名規則
Angular の命名規則
## FILE
# Componenti: kebab-case.component.ts
order-list.component.ts
order-detail.component.ts
user-profile-card.component.ts
# Servizi: kebab-case.service.ts
order.service.ts
auth.service.ts
notification.service.ts
# Models: kebab-case.model.ts
order.model.ts
user.model.ts
# Pipes: kebab-case.pipe.ts
currency-format.pipe.ts
date-ago.pipe.ts
# Guards: kebab-case.guard.ts
auth.guard.ts
role.guard.ts
## CLASSI
# Componenti: PascalCase + Component suffix
export class OrderListComponent
export class UserProfileCardComponent
# Servizi: PascalCase + Service suffix
export class OrderService
export class AuthService
# Models/Interfaces: PascalCase (no suffix)
export interface Order
export type OrderStatus = 'PENDING' | 'COMPLETED'
## SELETTORI
# Prefix app- + kebab-case
selector: 'app-order-list'
selector: 'app-user-card'
## VARIABILI
# Signals: nomeSignal o nome (opinabile)
ordersSignal = signal<Order[]>([]);
loading = signal(false);
# Observables: nome$ suffix
orders$ = this.http.get<Order[]>(...)
user$ = this.authService.currentUser$
# Boolean: is/has prefix
isLoading = signal(false);
hasError = signal(false);構成管理
Spring Boot: マルチ環境
application.yml - ベース
spring:
application:
name: order-service
datasource:
url: ${DATABASE_URL}
username: ${DATABASE_USER}
password: ${DATABASE_PASSWORD}
jpa:
hibernate:
ddl-auto: validate
open-in-view: false
app:
cors:
allowed-origins: ${CORS_ORIGINS:http://localhost:4200}
security:
jwt-secret: ${JWT_SECRET}
jwt-expiration: 3600000
アプリケーション開発.yml
spring:
datasource:
url: jdbc:postgresql://localhost:5432/orders_dev
jpa:
show-sql: true
logging:
level:
com.company.orders: DEBUG
org.hibernate.SQL: DEBUG
app:
cors:
allowed-origins: http://localhost:4200Angular: 環境ファイル
環境.ts
export const environment = {{ '{' }}
production: false,
apiUrl: 'http://localhost:8080/api/v1',
features: {{ '{' }}
enableAnalytics: false,
enableDarkMode: true,
{{ '}' }},
auth: {{ '{' }}
tokenKey: 'auth_token',
refreshTokenKey: 'refresh_token',
{{ '}' }}
{{ '}' }};コード構造チェックリスト
プロジェクト組織チェックリスト
- README に記載されているフォルダー構造
- 定義および共有された命名規則
- 機能ごとにパッケージ化して高い凝集性を実現
- 機能ごとに分けられた共有/コア
- 環境別の構成 (開発、ステージング、本番)
- クリーン輸入のためのバレル輸出
- ソースコードと併置されたテスト
結論と次のステップ
この記事では、コード構造の基礎を定義しました。 保守可能でスケーラブルです。で 次の記事、探索してみます の高度なテクニック 迅速なエンジニアリング 得る 複雑なシナリオではクロードから最も多くの恩恵を受けます。
覚えておくべき重要なポイント
- 機能ごとにパッケージ化: 関連するコードをまとめて保管する
- 一貫した命名: チーム全体の明確な約束事
- コア/共有/機能: 明確な責任の分離
- 環境ごとの構成: ハードコーディングされたものは何もなく、すべてが構成可能です
- 構造を文書化します。 フォルダーツリーを含む README