干净API设计

Question

这将是更好的方式来设计的API：

Example A: 
public class UserService { 
    public void addUser(final User user); 
    public void addUserToIndex(final User user, final int index); 
    public User lookUpUser(final User user); 
    public User getUserByIndex(final int index); 
    public void removeUser(final User user); 
    public List<User> getAllUsers(); 
} 

Example B: 
public class UserService { 
    public void add(final User user); 
    public void add(final User user, final int index); 
    public User lookUp(final User user); 
    public User get(final int index); 
    public void remove(final User user); 
    public List<User> getAll(); 
} 

显然，这代码将不会运行 - 它应该只是显示问题。我更喜欢第二种方法。方法名称可能有点通用，但上下文（className，parameter，return Type）使其非常清晰。第二种方法可能存在的一个问题是，如果我需要另一种具有相同Type的get方法，会发生什么情况。例如，如果我想让用户的年龄。预先感谢您的帮助。

裤裤

Answer 1

有两个主要问题，这些问题需要回答，让您选择更容易为：

1. 你绝对100％肯定，你将永远不会有一个以上的实体，该服务协议？

   换句话说，UserService会有其他方法，如getRoles()？如果答案是肯定的，你肯定会用选项A。

2. 如果你一定要有一个实体每个服务，你甚至需要一个每个服务的接口，或者你宁愿使用一个共同的通用的一个？

   因此，而不是你选择B你可以有这样的事情需要更具体的功能，可以再扩展这个通用服务

   public class Service<T> { 
       public void add(final T entity); 
       public void add(final T entity, final int index); 
       public T lookUp(final T entity); 
       public T get(final int index); 
       public void remove(final T entity); 
       public List<T> getAll(); 
   } 
   

   混凝土业务。

Answer 2

鉴于现代IDE这些天，我与托马斯同意，这是一个相当主观的问题。

你必须考虑代码可能最终看起来像什么（以及API的可能扩展）。

a.add(b); // :P this would make no sense at all 
a.addUser(b) // is at least more descriptive 

有一个争论和反对冗长的方法名称。我个人以现代IDE的能力来说，反对的观点正在慢慢减轻。

就个人而言，我更喜欢例如A，它是更清楚的了每个方法是做

Answer 3

您的问题是“越来越详细的” VS“感到困惑”的意图。由于通过查看方法名称来获得详细信息使客户端通过猜测功能进行编码。不过，我更喜欢第二个版本，因为方法签名（和返回类型）明确了它的作用。有了IDE支持和适当的评论/文档，第2版更简洁，同样方便。

有没有其他方式来解释UserService#add(User)将做除adding user以外的任何事情;其他方法也一样。该代码看起来很小，并且输入较少。

Answer 4

第一种方法似乎更清洁。提前了解更多信息。阅读代码的人会立即知道代码的含义，这在调试或维护别人的代码时很重要。

这里有两个例子是接近你从最好的设计框架2做什么：

JDK7

package java.security.acl 

public interface Group extends Principal 
{ 

    public boolean addMember(Principal user); 
    public boolean removeMember(Principal user); 
    public boolean isMember(Principal member); 
    public Enumeration<? extends Principal> members(); 
} 

春：

public interface GroupManager { 

    List<String> findAllGroups(); 
    List<String> findUsersInGroup(String groupName); 
    void createGroup(String groupName, List<GrantedAuthority> authorities); 
    void deleteGroup(String groupName); 
    void renameGroup(String oldName, String newName); 
    void addUserToGroup(String username, String group); 
    void removeUserFromGroup(String username, String groupName); 
    List<GrantedAuthority> findGroupAuthorities(String groupName); 
    void addGroupAuthority(String groupName, GrantedAuthority authority); 
    void removeGroupAuthority(String groupName, GrantedAuthority authority); 
} 

正如你所看到的从这些接口中，如果我正在阅读代码，就可以立即告诉代码在做什么，而不必回头查看对象的类型。

我投你的例子A.它只是让每个人的生活更简单。