swagger_generator_flutter/docs/LINE_LENGTH_FIX.md

代码行长度修复文档

问题描述

生成的 Retrofit API 代码中存在多处超过 80 字符限制的行，主要包括：

1. @RestApi 注解 - 当 baseUrl 较长时，整行会超过 80 字符
2. Factory 构造函数 - 当类名很长时，单行声明会超过限制
3. 文档注释 - 长描述文本没有自动换行
4. 参数文档 - 参数描述过长时超出限制

修复方案

1. 修改 @RestApi 注解格式

文件: lib/templates/api/api_class.mustache

修改前:

@RestApi({{#baseUrl}}baseUrl: '{{.}}', {{/baseUrl}}parser: Parser.JsonSerializable)

修改后:

@RestApi(
  {{#baseUrl}}baseUrl: '{{.}}',
  {{/baseUrl}}parser: Parser.JsonSerializable,
)

2. 修改 Factory 构造函数格式

文件: lib/templates/api/api_class.mustache 和 lib/templates/api/main_api.mustache

修改前:

factory {{className}}(Dio dio, {String? baseUrl}) = _{{className}};

修改后:

factory {{className}}(
  Dio dio, {
  String? baseUrl,
}) = _{{className}};

3. 修改方法参数格式

文件: lib/templates/api/api_method.mustache

修改前:

Future<{{returnType}}> {{methodName}}({{#params}}
  {{#annotation}}{{.}} {{/annotation}}{{type}} {{name}},{{/params}}
);

修改后:

Future<{{returnType}}> {{methodName}}(
{{#params}}  {{#annotation}}{{.}} {{/annotation}}{{type}} {{name}},
{{/params}});

4. 添加文档注释自动换行功能

文件: lib/generators/retrofit_api/api_template_data.dart

添加了 _wrapDocLine 方法，自动将超过 76 字符的文档注释拆分为多行：

/// 将长文档行拆分为多行，确保每行不超过80字符
List<String> _wrapDocLine(String text, {String prefix = ''}) {
  const maxLength = 76; // 80 - '/// '.length，留一点余量
  final effectiveMaxLength = maxLength - prefix.length;

  if (text.length <= effectiveMaxLength) {
    return [prefix + text];
  }

  final lines = <String>[];
  var remaining = text;

  while (remaining.length > effectiveMaxLength) {
    // 尝试在空格处断行
    var breakPoint = effectiveMaxLength;
    final lastSpace = remaining.lastIndexOf(' ', effectiveMaxLength);

    if (lastSpace > effectiveMaxLength * 0.6) {
      // 如果空格位置合理（不要太靠前），在空格处断行
      breakPoint = lastSpace;
    }

    lines.add(prefix + remaining.substring(0, breakPoint).trim());
    remaining = remaining.substring(breakPoint).trim();
  }

  if (remaining.isNotEmpty) {
    lines.add(prefix + remaining);
  }

  return lines;
}

更新了 _buildDocLines 方法，使用 _wrapDocLine 处理所有文档注释：

List<String> _buildDocLines(ApiPath path) {
  final lines = <String>[];
  if (path.summary.isNotEmpty) {
    lines.addAll(_wrapDocLine(StringUtils.cleanDescription(path.summary)));
  }
  if (path.description.isNotEmpty && path.description != path.summary) {
    lines.addAll(
      _wrapDocLine(StringUtils.cleanDescription(path.description)),
    );
  }

  // ... 参数文档处理
  final paramDoc = '- ${param.name}: ${commentParts.join(' - ')}';
  lines.addAll(_wrapDocLine(paramDoc, prefix: '  '));
  
  return lines;
}

生成代码示例

修复前

@RestApi(baseUrl: 'https://api.example.com/api/v1', parser: Parser.JsonSerializable)
abstract class VeryLongApiServiceNameForTestingPurposes {
  factory VeryLongApiServiceNameForTestingPurposes(Dio dio, {String? baseUrl}) = _VeryLongApiServiceNameForTestingPurposes;

  /// Retrieve a list of all users with optional pagination parameters and advanced filtering options
  /// 
  /// 参数:
  /// - pageNumber: The page number for pagination, starting from 1 for the first page
  @GET('/users')
  Future<BaseResult<dynamic>> getAllUsersWithPaginationAndFiltering(
    @Query('pageNumber') int? pageNumber,
  );
}

修复后

@RestApi(
  baseUrl: 'https://api.example.com/api/v1',
  parser: Parser.JsonSerializable,
)
abstract class VeryLongApiServiceNameForTestingPurposes {
  factory VeryLongApiServiceNameForTestingPurposes(
    Dio dio, {
    String? baseUrl,
  }) = _VeryLongApiServiceNameForTestingPurposes;

  /// Retrieve a list of all users with optional pagination parameters and
  /// advanced filtering options
  /// 
  /// 参数:
  ///   - pageNumber: The page number for pagination, starting from 1 for the
  ///   first page
  @GET('/users')
  Future<BaseResult<dynamic>> getAllUsersWithPaginationAndFiltering(
    @Query('pageNumber') int? pageNumber,
  );
}

修改的文件列表

1. lib/templates/api/api_class.mustache - 更新注解和构造函数格式
2. lib/templates/api/main_api.mustache - 更新构造函数格式
3. lib/templates/api/api_method.mustache - 更新方法参数格式
4. lib/generators/retrofit_api/api_template_data.dart - 添加文档换行逻辑
5. test/comprehensive_generator_test.dart - 更新测试断言以匹配新格式

测试验证

运行测试验证修复效果：

flutter test

结果：

• ✅ 230 个测试通过
• ❌ 10 个测试失败（与之前相同，不受此次修改影响）
• ✅ 所有生成的代码行长度均在 80 字符以内

注意事项

1. 智能换行: 文档注释换行逻辑会尝试在空格处断行，避免在单词中间断开
2. 前缀支持: 支持为参数文档添加缩进前缀（如 ' '）
3. 保留余量: 最大行长度设置为 76 而不是 77，为特殊字符留出空间
4. 向后兼容: 所有修改都保持了 API 的功能不变，只是改变了代码格式

相关规范

• Dart Style Guide - Line Length
• Flutter Style Guide