接口设计实例（接口设计案例）

本篇文章给大家谈谈接口设计实例，以及接口设计案例对应的知识点，希望对各位有所帮助，不要忘了收藏本站喔。 今天给各位分享接口设计实例的知识，其中也会对接口设计案例进行解释，如果能碰巧解决你现在面临的问题，别忘了关注本站，现在开始吧！

本文目录一览：

• 1、概要设计的接口设计怎么写
• 2、java对外接口怎么写
• 3、RESTful API 设计约定

概要设计的接口设计怎么写

接口设计包括三个方面：
一、用户接口
用来说明将向用户提供的命令和它们的语法结构，以及软件的回答信息。
二、外部接口
用来说明本系统同外界的所有接口的安排包括软件与硬件之间的接口、本系统与各支持软件之间的接口关系。
三、内部接口
用来说明本系统之内的各个系统元素之间的接口的安排

java对外接口怎么写

这个要结合面向对象设计思想去思考。
首先实例化的类作为一个角色，你可以把他理解为一个人。那么这个人肯定有与其他人（其他对象）交互的方法。那么这个方法也就别叫做接口。其实这算一种翻译上的过度强调。至少我理解的类的接口和方法是一回事。而interface定义的接口也算一种等待实现的方法。interface独特之处在于，任何实现了这个接口的类所产生的实例。都可以看作是这个interface的一个实例

所以说在设计接口和写对外方法（public）时一定要注意。这个方法（行为)是不是应该这个类（人）他应该具有的。否则就要考虑增加角色

RESTful API 设计约定

本文编写目的是为了尽可能的约定好一个公司的产品、组件、项目开发的RESTful API 设计风格，使不同团队间设计的API风格尽量一致，减少项目后期由于规范问题或设计不足导致的接口重构造成的开发、测试返工。最终让接口的最终使用者能够在开发过程中有个良好的体验。

此约定可作为开发人员设计RESTful 接口或项目接口发布评审的参考。

个人观点：用了 JSON-RPC 不等于 是RESTful API ，RESTful API通常是基于HTTP/JSON方式实现的 ，两种方式的API设计方式都不错，项目中选适合的就好。简单对比如下：

本文仅是作者个人根据主观喜好和接口设计经验搜罗总结而来的RESTful API设计约定，仅作为接口设计的基本要求，也欢迎与大家讨论。此约定未涉及超文本HATEOAS相关内容，也不包含RPC类面向后端服务方法映射接口的范畴。

API 是后端应用程序的脸面(UI)，用户体验非常重要。尤其是当你开发的是一个可复用的组件或产品，如果API设计有些许瑕疵，会直接影响开发者的体验，设计者会被骂的…… 有问题的API一旦开放出去了，哪怕是简单的拼写错误，由于要保持兼容性不能删改，会成为技术欠债长期背下去。

以上关键点不只适用于RESTful API，其他类型API也是一样的。

作为对外公开发布的RESTful API，根URL中一般要有域名与版本信息。通常一个WEB站点会同时提供网站服务和API服务，我们需要根据URL能够区分出访问的是服务接口还是网站中的网页、文件等资源。因此RESTful API的根URL中根据不同场景一般会在一级域名中或者是子域名中带api关键字。

常见的两种根URL用法如下：

推荐的方案是根URL中采用子域名的方式区分API，即： https://iam.primeton.com/api/v1/*

路径终点即粗体部分内容： https:// example.org/api/v1/ menus

设计RESTful API时常用的HTTP Method包括：GET、POST、PUT、PATCH、DELETE 简单说明如下：

根据资源标识可以 唯一定位一个资源 时，建议使用URL路径参数方式传递。对应Springboot 的 @PathVariable 。API Path示例如下：

根据资源属性查询过滤 一或多个资源 时，建议使用URL查询参数方式传递。对应Springboot的 @RequestParam 。API Path示例如下：

对于简单查询类接口，可以使用路径参数和查询参数解决，如果是复杂功能型查询接口中需要通过复杂的过滤条件查询时如： < in between 等等，查询参数用起来会非常痛苦，GET Method又不支持提交Request Body参数。因此我建议这种 复杂型查询采用POST Method 提交到一个特定的Path上 。参见如下场景：

查询接口返回多个数据时，需要支持分页（枚举类数据或少量数据除外）和排序。

如需使用分页查询和排序，建议统一请求与响应报文结构，格式如下：

请求参数示例：

GET /users?page=1size=5sort=username

单页数据响应结果示例：

上述分页排序与响应报文格式是来自Spring Data定义的模型，为了保持分页排序接口相关的使用习惯，如果持久化不使用JPA，仍然建议采用上述规范的报文定义封装接口。为使用者提供一致的体验。

如果资源需要做一些增删改之外的操作（如状态变更），可以用 /actions 作为path

例如：流程平台中的流程实例会有状态变化，如启动、挂起、恢复、终止等等，这种接口建议这样设计：

组合资源，即两种资源之间存在组合关系，组合指整体与部分的强包含关系，但整体与部分是不可分的，整体的生命周期结束也就意味着部分的生命周期结束。对"部分"的操作一定会由整体作为入口，不会直接跳过"整体"来对"部分"做增删改查。这种组合场景中，推荐API设计方式示例如下：

聚合资源，即两种资源之间存在聚合关系。聚合也是整体与部分的弱包含关系，但整体与部分之间是可分离的，他们可以具有各自的生命周期，部分可以属于多个不同的主体对象，也可以为多个整体对象共享。

例如，机构或角色下包含人员，需要获取机构或角色下的人员的场景，避免做成分别通过机构入口或角色入口找人等重复的具有类似功能的接口：

在RESTful API设计中，正常和异常情况建议通过HTTP约定的status进行区分， 不建议 采用所有接口均POST Method调用，永远返回200这种模式。

推荐的常用Http Status说明如下：

HTTP 1.0 Status 详细说明参考

API调用成功后，返回HTTP 2xx状态码，Response Body直接返回业务数据即可。请求和响应报文建议统一采用JSON格式。

RESTful API 对于异常报文需要规范和统一，服务端出现异常情况下，需要进行全局拦截，然后将异常信息封装为规范的格式，返回给调用端。

对于后端的异常信息，建议包含编码和消息

本文是基于学习各路大神们对RESTful 设计相关文章，结合自己设计接口时遇到困惑后的解决方案，收集与总结而成的RESTful API设计约定。部分内容夹杂个人喜好与主观观点，抛砖引玉，希望能为大家设计API带来些许帮助。后如果遇到一些更复杂的场景，欢迎一起沟通。

关于接口设计实例和接口设计案例的介绍到此就结束了，不知道你从中找到你需要的信息了吗 ？如果你还想了解更多这方面的信息，记得收藏关注本站。 接口设计实例的介绍就聊到这里吧，感谢你花时间阅读本站内容，更多关于接口设计案例、接口设计实例的信息别忘了在本站进行查找喔。

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。