Flutter中Retrofit生成代码出现无效覆写错误的技术咨询

常见问题原因及排查步骤 #

1. 方法签名不匹配 #

生成的实现类方法与抽象类定义的方法签名（参数类型、返回值类型、参数顺序/命名方式）不一致，是最常见的触发原因。

• 排查方式：逐行对比抽象类方法和生成的_xxxService类中的对应方法：
  • 检查返回值：比如抽象类定义Future<User>，生成代码是否误写为Future<dynamic>；
  • 检查参数：比如抽象类用了命名参数{required int id}，生成代码是否变成了位置参数；
  • 检查参数类型：比如抽象类参数是String，生成代码是否被替换为dynamic。

2. Retrofit注解使用错误 #

注解缺失或参数错误会导致生成器生成不符合预期的方法签名。

• 常见错误场景：
  • 路径占位符{xxx}没有对应@Path("xxx")注解；
  • 请求体没有添加@Body注解；
  • 查询参数没有添加@Query注解；
• 修复示例：

  // 错误写法
  @GET("/users/{id}")
  Future<User> getUser(int id);
  
  // 正确写法
  @GET("/users/{id}")
  Future<User> getUser(@Path("id") int id);
  

3. 实体类序列化配置缺失 #

如果返回值或请求体的实体类没有正确配置序列化，Retrofit生成器无法识别具体类型，会默认用dynamic替代，导致与抽象类的泛型返回值不匹配。

• 排查方式：
  • 确保实体类添加了@JsonSerializable()注解；
  • 确保已执行build_runner生成实体类的序列化代码；
• 正确示例：

  @JsonSerializable()
  class User {
    final int id;
    final String name;
  
    User({required this.id, required this.name});
  
    factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
    Map<String, dynamic> toJson() => _$UserToJson(this);
  }
  

4. 抽象类定义不符合规范 #

抽象类的定义格式错误会导致生成的实现类无法正确继承：

• 规范要求：
  • 必须是abstract class；
  • 必须添加@RestApi(baseUrl: "...")注解；
  • 必须包含工厂方法factory ApiService(Dio dio) => _ApiService(dio);；
• 正确示例：

  @RestApi(baseUrl: "https://api.example.com")
  abstract class ApiService {
    factory ApiService(Dio dio) => _ApiService(dio);
  
    @GET("/users")
    Future<List<User>> getUsers();
  }
  

5. 清理缓存后重新生成 #

Build runner的缓存可能导致生成代码异常，执行以下命令清理并重新生成：

dart run build_runner clean
dart run build_runner build --delete-conflicting-outputs

内容的提问来源于stack exchange，提问作者WhatIf