前言：在工作发现接口至关重要，特别需要把接口的注释写清楚，能调用的同事知道这个接口是干嘛用的，要传递什么参数等，在这里我做了一个简单的接口并生成帮助帮助，供大家相互学习，有好的可以提出来我继续改进。
第一步：建立一个用户接口（明确这个接口的作用）
按照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(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 }
用户接口
第四步：实现这个接口
因为项目一上线错误出现以后就很难发现，所以我们一定要加入日志系统，所以在项目中我加入了抛异常，然后通过日志就知道问题出现在哪里（没有实现功能）
1 /// <summary>
2 /// 实现用户相关操作
3 /// </summary>
4 public class User:IUser {
5
6 public bool Add(UserInfo userInfo)
7 {
8 try
9 {
10 if (userInfo == null)
11 throw new ArgumentNullException("userInfo");
12 if (string.IsNullOrEmpty(userInfo.Id))
13 throw new ArgumentException("userInfo.Id无效");
14 if (string.IsNullOrEmpty(userInfo.UserName))
15 throw new ArgumentException("userInfo.UserName无效");
16 if (string.IsNullOrEmpty(userInfo.PassWord))
17 throw new ArgumentException("userInfo.PassWord无效");
18 return false;
19 }
20 catch
21 {
22 throw new Exception("其他未知异常");
23 }
24 }
25
26 public bool Delete(string userName)
27 {
28 try
29 {
30 if (string.IsNullOrEmpty(userName))
31 throw new ArgumentException("UserName无效");
32 return false;
33 }
34 catch
35 {
36 throw new Exception("其他未知异常");
37 }
38 }
39
40 public bool Delete(IList<string> userNames)
41 {
42 try
43 {
44 if (userNames == null)
45 throw new ArgumentNullException("userNames");
46 if (!userNames.Any())
47 throw new ArgumentException("userNames无效");
48 return false;
49 }
50 catch
51 {
52 throw new Exception("其他未知异常");
53 }
54 }
55
56 public bool Update(UserInfo userInfo)
57 {
58 try
59 {
60 if (userInfo == null)
61 throw new ArgumentNullException("userInfo");
62 if (string.IsNullOrEmpty(userInfo.UserName))
63 throw new ArgumentException("userInfo.UserName无效");
64 return false;
65 }
66 catch
67 {
68 throw new Exception("其他未知异常");
69 }
70
71 }
72
73 public UserInfo Get(string userName)
74 {
75 try
76 {
77 if (string.IsNullOrEmpty(userName))
78 throw new ArgumentException("UserName无效");
79 return null;
80 }
81 catch {
82 throw new Exception("其他未知异常");
83 }
84 }
85
86 public IList<UserInfo> Get(IList<string> userNames)
87 {
88 try
89 {
90 if (userNames == null)
91 throw new ArgumentNullException("userNames");
92 if (!userNames.Any())
93 throw new ArgumentException("userNames无效");
94 return null;
95 }
96 catch {
97 throw new Exception("其他未知异常");
98 }
99
100 }
101
102 public IList<UserInfo> Get(UserEnum.ProfessionalType professional)
103 {
104 try
105 {
106 if (professional >= (UserEnum.ProfessionalType)4)
107 throw new ArgumentOutOfRangeException("professional");
108 return null;
109 }
110 catch {
111 throw new Exception("其他未知异常");
112 }
113
114 }
115 }
实现接口
第五步：点击项目属性，找到生成勾选xml文档文件如下图
第六步：下载一个Sandcastle Help File Builder 然后安装，安装成功以后，找到Sandcastle Help File Builder新建一个项目如下图
第七步：找到生成的dll和xml文件然后导入如下图
第八步：点击生成按钮就可以生成一篇帮助文档了
生成帮助文档的效果
以上就是整个效果，大家有好的欢迎相互讨论。
时间： 2024-08-11 13:26:06