提供给外部调用的接口设计有哪些原则和技巧？

Question

提供给外部调用的接口设计有哪些原则和技巧？

有几个问题一直想问：

1、远程接口是应该抛出异常，还是封装返回值？
2、接口需不需要容错处理，还是交给调用方容错。
3、接口升级的考虑，怎么做到客户端容易升级？序列化的容错？
4、对读写分离接口的理解，如readService和writeService。为什么有接口这么区分
5、参数Map还是类比较好？
6、参数是常量还是enum比较好？

Answer 1

1、如果提供给内部其他应用使用
1、远程接口是应该抛出异常，还是封装返回值？ 抛出异常最好，这样客户可以查看javadoc更加容易的来处理错误，而不需要ifelse判断返回值；
2、接口需不需要容错处理，还是交给调用方容错。 采用断言定义前置条件（如果前提不满足直接抛出异常给客户 告诉客户参数有误） 一定的容错还是需要的；
3、接口升级的考虑，怎么做到客户端容易升级？序列化的容错？ 必须向后兼容，不采用java的序列号，而采用语言/平台无关的文本方式如JSON、XML交互数据；跨平台 跨语言；
4、对读写分离接口的理解，如readService和writeService。为什么有接口这么区分：这个不一定这么分 而是要根据需求不同定义接口 不要定义大而全的接口
5、参数Map还是类比较好？ 当然类更好 可以考虑 JSON-->类的转换工具；
6、参数是常量还是enum比较好？ enum更好 更安全 而且表达能力更强；

2、提供给第三方应用使用，比如通过http协议暴露
1、远程接口是应该抛出异常，还是封装返回值？ 封装返回值，因为可能是不同平台调用
3、接口升级的考虑，怎么做到客户端容易升级？序列化的容错？ 采用语言/平台无关的文本方式如JSON、XML交互数据；跨平台 跨语言；
5和6可以利用一些工具自动进行Mapping