Durations

DurationStyle は、期間を短い形式 10s と ISO-8601 の PT10S の両方でテキストとして読み書きします。

使う理由

タイムアウト、間隔、キャッシュの有効期間は期間です。設定には 30000 ではなく 30s と書けるべきで、コードは解釈が必要な数値ではなく Dart の Duration を受け取るべきです。デフォルトの変換サービスは、文字列を Duration にするたびに DurationStyle.parse を呼びます。対象は @Value、getPropertyAs<Duration>、@ConfigurationProperties のフィールドです。DurationStyle を自分で呼ぶのは、独自のコードで期間を解析または出力するときだけです。

受け付ける形式:

• 短い形式: 整数と、省略可能な単位 ns、us、ms、s、m、h、d(大文字小文字は問わない)。例: 500ms、10s、-2h、2d。
• ISO-8601: PT10S、PT1H30M、P1DT2H、PT0.5S。負の値は -PT5S。年と月は受け付けません。
• 単位のない数値: ミリ秒。@DurationUnit(spring_boot_dart のアノテーション)を使うと、@ConfigurationProperties のフィールドでこの単位を変えられます。

例

# lib/resources/application.properties
shop.timeout=30s
shop.retry-after=PT1M30S
shop.poll=250

import 'package:spring_core_dart/spring_core_dart.dart';

@Service()
class Poller {
  Poller(
    @Value(r'${shop.timeout}') this.timeout, // 30 秒
    @Value(r'${shop.retry-after}') this.retryAfter, // 1 分 30 秒
    @Value(r'${shop.poll}') this.poll, // 250 ミリ秒
  );

  final Duration timeout;
  final Duration retryAfter;
  final Duration poll;
}

コードでの使い方:

DurationStyle.parse('500ms'); // Duration(milliseconds: 500)
DurationStyle.parse('P1DT2H'); // Duration(days: 1, hours: 2)
DurationStyle.parse('30', unit: ChronoUnit.seconds); // 30 秒
DurationStyle.format(const Duration(minutes: 90)); // '90m'
DurationStyle.formatIso(const Duration(minutes: 90)); // 'PT1H30M'
ChronoUnit.seconds.of(30); // Duration(seconds: 30)

メンバー

DurationStyle(静的メソッド):

ChronoUnit の値: nanos、micros、millis、seconds、minutes、hours、days。unit.of(amount) で Duration を得られます。

Spring (Java) との対応

// Spring Boot
Duration d = DurationStyle.detectAndParse("500ms");
Duration iso = DurationStyle.detectAndParse("P1DT2H");
String text = DurationStyle.SIMPLE.print(Duration.ofMinutes(90));
String isoText = DurationStyle.ISO8601.print(Duration.ofMinutes(90));

重要な違い:

• parse は Spring Boot の detectAndParse と同じく形式を自動判別します。format と formatIso は SIMPLE.print と ISO8601.print に当たります。
• Dart の Duration の精度はマイクロ秒なので、ns の値はマイクロ秒に切り捨てられます。
• ChronoUnit には Duration が保持できる単位(ナノ秒から日まで)しかありません。月と年はありません。
• Spring では期間の解析は Spring Boot の機能です。ここではコアの一部です。

関連項目

• ConversionService
• DataSize
• @Value
• @ConfigurationProperties