我的設計接口總結以及生成幫助文檔

  前言：在工作發現接口至關重要，特別需要把接口的注釋寫清楚，能調用的同事知道這個接口是干嘛用的，要傳遞什么參數等，在這里我做了一個簡單的接口並生成幫助幫助，供大家相互學習，有好的可以提出來我繼續改進。

第一步：建立一個用戶接口（明確這個接口的作用）

按照Add，Delete，Update，Get模式來定義接口的方法（我個人覺得盡可能的重載）

第二步：方法中寫出盡可能詳盡的注釋

按照方法實現的功能，參數意思，異常，備注，返回值等來寫

第三步：接口中如果出現參數為類型的時候千萬不要用1,2這樣的數值代替盡可能用枚舉

為什么用枚舉：因為在實際項目中可能做到最后的時候自己都不知道1代表什么2代表什么，通過枚舉就能解決這些問題，而且枚舉擴展性也很好

現在我們看一下我寫的接口

/// <summary>
    /// 關於用戶信息的操作
    /// </summary>
    public interface IUser
    {
        /// <summary>
        /// 添加用戶信息
        /// </summary>
        /// <param name="userInfo">用戶實體</param>
        /// <exception cref="ArgumentNullException">userInfo為null</exception>
        /// <exception cref="ArgumentException">userInfo.Id為空字符串</exception>        
        /// <exception cref="ArgumentException">userInfo.UserName為空字符串</exception>
        /// <exception cref="ArgumentException">userInfo.PassWord為空字符串</exception>
        /// <exception cref="Exception">其他未知異常</exception>
        /// <returns>true：添加成功 false：添加失敗</returns>
        bool Add(UserInfo userInfo);

        /// <summary>
        /// 根據用戶名刪除用戶
        /// </summary>
        /// <param name="userName">用戶名</param>
        /// <exception cref="ArgumentException">userName為空字符串</exception>
        /// <exception cref="Exception">其他未知異常</exception>
        /// <returns>true：刪除成功 false：刪除失敗</returns>
        bool Delete(string userName);

        /// <summary>
        /// 根據用戶名批量刪除用戶
        /// </summary>
        /// <param name="userNames">用戶名（可以單個也可以多個）</param>
        /// <exception cref="ArgumentNullException">userNames為null</exception>
        /// <exception cref="ArgumentException">userNames不是有效參數</exception>
        /// <exception cref="Exception">其他未知異常</exception>
        ///<remarks>加入事物，如果其中一條未能刪除成功，所有數據進行回滾</remarks>
        /// <returns>true：刪除成功 false：刪除失敗</returns>
        bool Delete(IList<string> userNames);

        /// <summary>
        /// 更新用戶信息
        /// </summary>
        /// <exception cref="ArgumentNullException">userInfo為null</exception>
        /// <exception cref="ArgumentException">userInfo.UserName為空字符串</exception>    
        /// <exception cref="Exception">其他未知異常</exception>
        /// <returns>true：更新成功 false：更新失敗</returns>
        bool Update(UserInfo userInfo);

        /// <summary>
        /// 根據用戶名獲取用戶信息
        /// </summary>
        /// <exception cref="ArgumentException">userName為空字符串</exception>
        /// <exception cref="Exception">其他未知異常</exception>
        /// <returns>返回一條用戶信息可為null</returns>
        UserInfo Get(string userName);

        /// <summary>
        /// 根據用戶名獲取批量用戶信息
        /// </summary>
        /// <param name="userNames">用戶名（可以單個也可以多個）</param>        
        /// <exception cref="ArgumentNullException">userNames為null</exception>
        /// <exception cref="ArgumentException">userNames不是有效參數</exception>
        /// <exception cref="Exception">其他未知異常</exception>
        /// <remarks>如果返回結果為空則返回一條沒有任何用戶的結果集</remarks>
        /// <returns>獲取用戶集</returns>
        IList<UserInfo> Get(IList<string> userNames);

        /// <summary>
        /// 根據職稱類型獲取用戶信息
        /// </summary>
        /// <param name="professional"></param>
        /// <exception cref="ArgumentOutOfRangeException">professional枚舉不在范圍內</exception>    
        /// <exception cref="Exception">其他未知異常</exception>
        /// <returns>獲取用戶集</returns>
        IList<UserInfo> Get(UserEnum.ProfessionalType professional);
    }

第四步：實現這個接口

因為項目一上線錯誤出現以后就很難發現，所以我們一定要加入日志系統，所以在項目中我加入了拋異常，然后通過日志就知道問題出現在哪里（沒有實現功能）

    /// <summary>
    /// 實現用戶相關操作
    /// </summary>
    public class User:IUser {

        public bool Add(UserInfo userInfo)
        {
            try
            {
                if (userInfo == null)
                    throw new ArgumentNullException("userInfo");
                if (string.IsNullOrEmpty(userInfo.Id))
                    throw new ArgumentException("userInfo.Id無效");
                if (string.IsNullOrEmpty(userInfo.UserName))
                    throw new ArgumentException("userInfo.UserName無效");
                if (string.IsNullOrEmpty(userInfo.PassWord))
                    throw new ArgumentException("userInfo.PassWord無效");
                return false;
            }
            catch
            {
                throw new Exception("其他未知異常");
            }
        }

        public bool Delete(string userName)
        {
            try
            {
                if (string.IsNullOrEmpty(userName))
                    throw new ArgumentException("UserName無效");
                return false;
            }
            catch
            {
                throw new Exception("其他未知異常");
            }
        }

        public bool Delete(IList<string> userNames)
        {
            try
            {
                if (userNames == null)
                    throw new ArgumentNullException("userNames");
                if (!userNames.Any())
                    throw new ArgumentException("userNames無效");
                return false;
            }
            catch 
            {
                throw new Exception("其他未知異常");                
            }            
        }

        public bool Update(UserInfo userInfo)
        {
            try
            {
                if (userInfo == null)
                    throw new ArgumentNullException("userInfo");
                if (string.IsNullOrEmpty(userInfo.UserName))
                    throw new ArgumentException("userInfo.UserName無效");
                return false;
            }
            catch
            {
                throw new Exception("其他未知異常");
            }
            
        }

        public UserInfo Get(string userName)
        {
            try
            {
                if (string.IsNullOrEmpty(userName))
                    throw new ArgumentException("UserName無效");
                return null;
            }
            catch {
                throw new Exception("其他未知異常");
            }    
        }

        public IList<UserInfo> Get(IList<string> userNames)
        {
            try
            {
                if (userNames == null)
                    throw new ArgumentNullException("userNames");
                if (!userNames.Any())
                    throw new ArgumentException("userNames無效");
                return null;
            }
            catch {
                throw new Exception("其他未知異常");
            }    
            
        }

        public IList<UserInfo> Get(UserEnum.ProfessionalType professional)
        {
            try
            {
                if (professional >= (UserEnum.ProfessionalType)4)
                    throw new ArgumentOutOfRangeException("professional");
                return null;
            }
            catch {
                throw new Exception("其他未知異常");
            }    
            
        }
    }

第五步：點擊項目屬性，找到生成勾選xml文檔文件如下圖

第六步：下載一個Sandcastle Help File Builder 然后安裝，安裝成功以后，找到Sandcastle Help File Builder新建一個項目如下圖

 

第七步：找到生成的dll和xml文件然后導入如下圖

第八步：點擊生成按鈕就可以生成一篇幫助文檔了

生成幫助文檔的效果

 

以上就是整個效果，大家有好的歡迎相互討論。