我的设计接口总结以及生成帮助文档

  前言：在工作发现接口至关重要，特别需要把接口的注释写清楚，能调用的同事知道这个接口是干嘛用的，要传递什么参数等，在这里我做了一个简单的接口并生成帮助帮助，供大家相互学习，有好的可以提出来我继续改进。

第一步：建立一个用户接口（明确这个接口的作用）

按照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

原标题：我的设计接口总结以及生成帮助文档

关键词：接口