前言:在工作发现接口至关重要,特别需要把接口的注释写清楚,能调用的同事知道这个接口是干嘛用的,要传递什么参数等,在这里我做了一个简单的接口并生成帮助帮助,供大家相互学习,有好的可以提出来我继续改进。第一步:建立一个用户接口(明确这个接口的作用)按照Add,Delete,Updat ...
前言:在工作发现接口至关重要,特别需要把接口的注释写清楚,能调用的同事知道这个接口是干嘛用的,要传递什么参数等,在这里我做了一个简单的接口并生成帮助帮助,供大家相互学习,有好的可以提出来我继续改进。
第一步:建立一个用户接口(明确这个接口的作用)
按照Add,Delete,Update,Get模式来定义接口的方法(我个人觉得尽可能的重载)
第二步:方法中写出尽可能详尽的注释
按照方法实现的功能,参数意思,异常,备注,返回值等来写
第三步:接口中如果出现参数为类型的时候千万不要用1,2这样的数值代替尽可能用枚举
为什么用枚举:因为在实际项目中可能做到最后的时候自己都不知道1代表什么2代表什么,通过枚举就能解决这些问题,而且枚举扩展性也很好
现在我们看一下我写的接口
1 /// <summary> 2 /// 关于用户信息的操作 3 /// </summary> 4 public interface IUser 5 { 6 /// <summary> 7 /// 添加用户信息 8 /// </summary> 9 /// <param name="userInfo">用户实体</param>10 /// <exception cref="ArgumentNullException">userInfo为null</exception>11 /// <exception cref="ArgumentException">userInfo.Id为空字符串</exception> 12 /// <exception cref="ArgumentException">userInfo.UserName为空字符串</exception>13 /// <exception cref="ArgumentException">userInfo.PassWord为空字符串</exception>14 /// <exception cref="Exception">其他未知异常</exception>15 /// <returns>true:添加成功 false:添加失败</returns>16 bool Add(UserInfo userInfo);17 18 /// <summary>19 /// 根据用户名删除用户20 /// </summary>21 /// <param name="userName">用户名</param>22 /// <exception cref="ArgumentException">userName为空字符串</exception>23 /// <exception cref="Exception">其他未知异常</exception>24 /// <returns>true:删除成功 false:删除失败</returns>25 bool Delete(get='_blank'>string userName);26 27 /// <summary>28 /// 根据用户名批量删除用户29 /// </summary>30 /// <param name="userNames">用户名(可以单个也可以多个)</param>31 /// <exception cref="ArgumentNullException">userNames为null</exception>32 /// <exception cref="ArgumentException">userNames不是有效参数</exception>33 /// <exception cref="Exception">其他未知异常</exception>34 ///<remarks>加入事物,如果其中一条未能删除成功,所有数据进行回滚</remarks>35 /// <returns>true:删除成功 false:删除失败</returns>36 bool Delete(IList<string> userNames);37 38 /// <summary>39 /// 更新用户信息40 /// </summary>41 /// <exception cref="ArgumentNullException">userInfo为null</exception>42 /// <exception cref="ArgumentException">userInfo.UserName为空字符串</exception> 43 /// <exception cref="Exception">其他未知异常</exception>44 /// <returns>true:更新成功 false:更新失败</returns>45 bool Update(UserInfo userInfo);46 47 /// <summary>48 /// 根据用户名获取用户信息49 /// </summary>50 /// <exception cref="ArgumentException">userName为空字符串</exception>51 /// <exception cref="Exception">其他未知异常</exception>52 /// <returns>返回一条用户信息可为null</returns>53 UserInfo Get(string userName);54 55 /// <summary>56 /// 根据用户名获取批量用户信息57 /// </summary>58 /// <param name="userNames">用户名(可以单个也可以多个)</param> 59 /// <exception cref="ArgumentNullException">userNames为null</exception>60 /// <exception cref="ArgumentException">userNames不是有效参数</exception>61 /// <exception cref="Exception">其他未知异常</exception>62 /// <remarks>如果返回结果为空则返回一条没有任何用户的结果集</remarks>63 /// <returns>获取用户集</returns>64 IList<UserInfo> Get(IList<string> userNames);65 66 /// <summary>67 /// 根据职称类型获取用户信息68 /// </summary>69 /// <param name="professional"></param>70 /// <exception cref="ArgumentOutOfRangeException">professional枚举不在范围内</exception> 71 /// <exception cref="Exception">其他未知异常</exception>72 /// <returns>获取用户集</returns>73 IList<UserInfo> Get(UserEnum.ProfessionalType professional);74 }
海外公司注册、海外银行开户、跨境平台代入驻、VAT、EPR等知识和在线办理:https://www.xlkjsw.com
原标题:我的设计接口总结以及生成帮助文档
关键词:接口
*特别声明:以上内容来自于网络收集,著作权属原作者所有,如有侵权,请联系我们:
admin#shaoqun.com
(#换成@)。