API命名规范

目录

• 背景和价值
  • • 🔍 一、实体查询（单对象获取）
      • 命名模式：get + 名词单数
      • 示例代码：
      • ✅ 规范要点：
    • 📋 二、实体列表查询（多对象获取）
      • 命名模式：list + 名词复数
      • 示例代码：
      • ✅ 规范要点：
    • 📄 三、分页列表查询（列表+分页）
      • 命名模式：list + 名词复数 + WithPaging
      • 示例代码：
      • ✅ 规范要点：
    • 📊 三类方法命名对比
• 参考资料

背景和价值

根据Google Java风格指南及相关API设计规范，以下是针对实体查询、实体列表查询及分页查询的方法命名规范总结：

---

🔍 一、实体查询（单对象获取）

命名模式：get + 名词单数

适用场景：获取单个实体（如根据ID查询）。
规范要求：

• 动词：固定使用 get，表示明确的数据获取动作。
• 名词：使用目标实体的单数形式（如 User、Order）。
• 参数命名：明确标识查询依据（如 id、email），避免缩写。

示例代码：

// 根据ID获取用户
public User getUserById(String userId);

// 根据邮箱获取订单
public Order getOrderByEmail(String email);

✅ 规范要点：

① 禁止使用 fetch/retrieve 等替代动词（违反一致性）；
② 参数名需体现查询键（如 ByXXX 后缀增强可读性）。

---

📋 二、实体列表查询（多对象获取）

命名模式：list + 名词复数

适用场景：获取全部或条件过滤的实体列表。
规范要求：

• 动词：使用 list，明确表示返回集合。
• 名词：使用目标实体的复数形式（如 Users、Orders）。
• 返回值：返回 List<T> 类型，禁止直接返回数组。

示例代码：

// 获取所有用户列表
public List<User> listUsers();

// 获取特定状态的订单
public List<Order> listOrdersByStatus(OrderStatus status);

✅ 规范要点：

① 避免使用 getAllXXX（冗长且破坏动词一致性）；
② 过滤条件通过参数或方法名后缀表达（如 ByStatus）。

---

📄 三、分页列表查询（列表+分页）

命名模式：list + 名词复数 + WithPaging

适用场景：需分页返回的实体列表（含页码、页大小）。
规范要求：

• 动词：沿用 list 表示集合操作。
• 参数命名：
  • pageNum：当前页码（从1开始）。
  • pageSize：每页条目数。
• 返回值：返回分页封装对象（如 Page<T>），包含列表及元数据（总页数、总数）。

示例代码：

// 分页查询用户列表
public Page<User> listUsersWithPaging(int pageNum, int pageSize);

// 分页+状态过滤的订单
public Page<Order> listOrdersByStatusWithPaging(OrderStatus status, int pageNum, int pageSize);

✅ 规范要点：

① 避免将分页参数命名为 offset/limit（语义不明确）；
② 返回封装对象而非裸列表，便于扩展分页元数据。

---

📊 三类方法命名对比

场景	命名模式	参数示例	返回值类型
单实体查询	get + 名词单数	(String id)	User
列表查询（无分页）	list + 名词复数	(OrderStatus status)	List<Order>
列表查询（分页）	list + 名词复数 + WithPaging	(int pageNum, int pageSize)	Page<Order>

参考资料