77> 📖 用語・共通概念は [ 用語集] ( ../../../README.md ) を参照
88
99``` python
10- from infrastructure import load_json, save_json, log_info, log_error
11- from infrastructure.file_scanner import scan_files, get_max_numbered_file
10+ from infrastructure import (
11+ # JSON操作
12+ load_json, save_json, load_json_with_template, file_exists, ensure_directory,
13+ # ファイルスキャン
14+ scan_files, get_files_by_pattern, get_max_numbered_file, filter_files_after_number, count_files,
15+ # ロギング
16+ get_logger, setup_logging, log_info, log_warning, log_error, log_debug,
17+ # 構造化ロギング
18+ StructuredLogger, get_structured_logger,
19+ # エラーハンドリング
20+ safe_file_operation, safe_cleanup, with_error_context,
21+ # ユーザーインタラクション
22+ get_default_confirm_callback,
23+ )
1224```
1325
1426---
@@ -194,6 +206,7 @@ def setup_logging(level: Optional[int] = None) -> logging.Logger
194206def log_info(message: str ) -> None
195207def log_warning(message: str ) -> None
196208def log_error(message: str , exit_code: Optional[int ] = None ) -> None
209+ def log_debug(message: str ) -> None
197210```
198211
199212環境変数でログ設定をカスタマイズ可能:
@@ -202,6 +215,129 @@ def log_error(message: str, exit_code: Optional[int] = None) -> None
202215
203216-- -
204217
218+ # # 構造化ロギング（infrastructure/structured_logging.py）
219+
220+ LOG_PREFIX_ * 定数を使用したボイラープレートを統合し、一貫したログ出力を提供。
221+
222+ # ## get_structured_logger()
223+
224+ ```python
225+ def get_structured_logger (name : str ) -> StructuredLogger
226+ ```
227+
228+ 構造化ロガーのインスタンスを取得。
229+
230+ ```python
231+ logger = get_structured_logger(__name__ )
232+ logger.state(" cascade_update" level = " weekly" count = 5 )
233+ # -> [DEBUG] [STATE] cascade_update: level=weekly count=5
234+ ```
235+
236+ # ## StructuredLogger
237+
238+ ```python
239+ class StructuredLogger:
240+ def info (message : str ) -> None # 一般的な情報ログ
241+ def state(message: str , ** context) -> None # 状態変化のログ [STATE]
242+ def file_op(message: str , ** context) -> None # ファイル操作のログ [FILE]
243+ def validation(message: str , ** context) -> None # 検証処理のログ [VALIDATE]
244+ def decision(message: str , ** context) -> None # 判断分岐のログ [DECISION]
245+ ```
246+
247+ ** 使用例** :
248+
249+ ```python
250+ logger = get_structured_logger(__name__ )
251+
252+ # 従来のコード
253+ log_debug(f " { LOG_PREFIX_STATE } cascade_update: level= { level} , count= { count} " )
254+
255+ # 新しいコード
256+ logger.state(" cascade_update" level = level, count = count)
257+ ```
258+
259+ ---
260+
261+ ## エラーハンドリング（infrastructure/error_handling.py）
262+
263+ ファイル操作等のエラー処理を統一するユーティリティ関数。
264+
265+ ### safe_file_operation()
266+
267+ ``` python
268+ def safe_file_operation (
269+ operation : Callable[[], T],
270+ context : str ,
271+ on_error : Optional[Callable[[Exception ], T]] = None ,
272+ * ,
273+ reraise : bool = False ,
274+ ) -> Optional[T]
275+ ```
276+
277+ ファイル操作を安全に実行するラッパー。一般的なファイルI/ Oエラーをキャッチし、一貫した方法で処理する。
278+
279+ ```python
280+ # 基本的な使用（エラーを無視）
281+ safe_file_operation(lambda : file_path.unlink(), " delete file"
282+
283+ # フォールバック付き
284+ result = safe_file_operation(
285+ lambda : load_json(path),
286+ " load config"
287+ on_error = lambda e : {}
288+ )
289+
290+ # エラーを再送出
291+ safe_file_operation(
292+ lambda : save_json(path, data),
293+ " save config"
294+ reraise = True
295+ )
296+ ```
297+
298+ # ## safe_cleanup()
299+
300+ ```python
301+ def safe_cleanup(
302+ cleanup_func: Callable[[], None ],
303+ context: str ,
304+ * ,
305+ log_on_error: bool = True ,
306+ ) -> bool
307+ ```
308+
309+ クリーンアップ操作を安全に実行する。エラーが発生しても処理を継続し、オプションで警告をログ出力。
310+
311+ ```python
312+ success = safe_cleanup(
313+ lambda : temp_file.unlink(),
314+ " remove temporary file"
315+ )
316+ if not success:
317+ print (" Cleanup failed but continuing..."
318+ ```
319+
320+ ### with_error_context()
321+
322+ ``` python
323+ def with_error_context (
324+ operation : Callable[[], T],
325+ context : str ,
326+ error_type : type = FileIOError,
327+ ) -> T
328+ ```
329+
330+ 操作を実行し、エラー時にコンテキスト付きの例外を送出。
331+
332+ ```python
333+ data = with_error_context(
334+ lambda : json.load(f),
335+ " parsing config.json"
336+ )
337+ ```
338+
339+ -- -
340+
205341# # ユーザーインタラクション（infrastructure/user_interaction.py）
206342
207343# ## get_default_confirm_callback()
0 commit comments