Hanson.Common.HttpUtils 2.5.0

README

Hanson.Common.HttpUtils

主要功能

1. 提供 Http 基本功能
   • Url 路徑合併
   • 讀取 URL 文字內容
   • 下載 URL 檔案
2. 提供 AuditRecorder 稽核中介層，用於記錄系統操作紀錄與稽核軌跡（登入登出、CRUD、下載、匯出、權限異動）

前置條件

• 開發環境需具備 .Net 8.0
• 運行於 Windows Platform (x64)
• 運行於 Linux Platform (x64)
• 運行於 Raspberry PI Platform (x64)

安裝方式

• 採用 Nuget 方式進行安裝作業 https://www.nuget.org/packages/Hanson.Common.HttpUtils/

授權

此專案採用的 License為 Apache-2.0

使用範例

命名空間

using Hanson.Common.Utils;

• URL 合併範例

private void Sample()
{
    var urlPath1 = @"http://127.0.0.1";
    var subUrlPath = @"combine";
	var htmlName = "index.html";
    
    // 合併 URL
	string url = HttpUtils.UrlCombine(urlPath1, subUrlPath, htmlName);
    Console.WriteLine($"合併 URL - 執行結果: {url}");
}

• 內容讀取範例

private static async Task SampleAsync()
{
    var url = @"https://www.google.com/";
    
    // 讀取 URL 網頁內容
    var content = await HttpUtils.GetUrlContentAsync(url);
    Console.WriteLine($"讀取 URL - 執行結果: {content}");
}

• 檔案下載範例

private static async Task SampleAsync()
{
    var path = @"c:\temp\index.html";
    var url = @"https://www.google.com/";
    //  下載 URL 檔案 
    var status = await HttpUtils.DownloadFileAsync(url, path);
    Console.WriteLine($"下載執行結果: {status}");
}

• 信件發送使用範例

private static bool Sample()
{
   var account = "test@gmail.com";
   var pwd = "pwd";
   var to = "irene@gmail.com";
   var cc = "irene@gmail.com;hanson@gmail.com";
   var client = new SmtpUtils(account, pwd, "smtp.office365.com");
   return client.SendMail(subject, body, to, cc);

}

• API GetAync 使用範例

private static async Task Sample()
{
   var token = @"eyJhbGciOiJIUzI1NiIsInR5cCI";
    var url = "http://localhost:8080/api/token";
    var client = new HttpClient();
    (bool state, string content) = await  GetAsync(client, url,token);
}

• API PostAync 使用範例

private static async Task Sample()
{
    var token = @"eyJhbGciOiJIUzI1NiIsInR5cCI"
    var body = @"{ ""account"": ""app"", ""password"": ""pwd""}";
    var url = "http://localhost:808/api/login/token";
    var client = new HttpClient();
    (bool state, string content) = await  PostAsync(client, url,body,token);
}

• AuditRecorder 稽核中介層使用範例

  預設落地方式為 NLogAuditRecorder：不寫入資料庫，改以結構化事件透過 NLog 輸出（Logger 名稱固定為 "Audit"）， 交由主機端 NLog.config（例如 Hanson.NLog.Config 內建的 GELF Target）匯出至 ELK。 若要改用其他落地方式（例如寫入資料庫），在 AddAuditRecorder() 之後再註冊自己的 IAuditRecorder 覆蓋即可（後註冊者優先）。

  1. 於 Program.cs / Startup.cs 註冊服務並掛載 Middleware

  // 註冊：AddAuditRecorder() 會同時註冊 IAuditContext，並以 NLogAuditRecorder 做為 IAuditRecorder 的預設實作
  builder.Services.AddAuditRecorder();
  
  // 如需改用其他落地方式（例如寫入資料庫），在 AddAuditRecorder() 之後覆蓋：
  // builder.Services.AddScoped<IAuditRecorder, DbAuditRecorder>();
  
  // 建置管線：務必放在 UseRouting/UseAuthentication/UseAuthorization 之後、端點執行之前
  app.UseRouting();
  app.UseAuthentication();
  app.UseAuthorization();
  app.UseAuditRecorder();
  app.MapControllers();
  

  若完全沒呼叫 AddAuditRecorder()，UseAuditRecorder() 會在啟動階段直接拋出 InvalidOperationException，避免上線後才發現稽核資料遺漏。

  操作者帳號解析優先順序：IAuditContext.Account 手動覆寫 → 解析 Authorization 的 Bearer Token（JWT）Payload 中的 account Claim（僅解碼、不驗證簽章，純粹作為稽核標籤用途）→ 已驗證身分 HttpContext.User 的 Claims（fallback）。 若 Token 內的帳號 Claim 名稱不是 account，可自行指定：

  builder.Services.AddAuditRecorder(options => options.BearerAccountClaim = "sub");
  

  2. 於 Controller Action 標記 AuditAttribute

  [HttpPut("{id}")]
  [Audit(AuditAction.Update, "會員", "更新會員資料")]
  public async Task<IActionResult> UpdateMember(int id, MemberUpdateContract contract)
  {
      // ...
  }
  
  [HttpDelete("{id}")]
  [Audit(AuditAction.Delete, "訂單")]
  public async Task<IActionResult> DeleteOrder(int id)
  {
      // ...
  }
  

  未標記 AuditAttribute 的端點不會被記錄。

  3. 於 Action 內以 IAuditContext 附加明細或覆寫操作者帳號（例如登入流程於驗證帳密通過後才知道帳號）

  [HttpPost("login")]
  [Audit(AuditAction.Login, "登入")]
  public async Task<IActionResult> Login(LoginContract contract, [FromServices] IAuditContext auditContext)
  {
      var account = await _accountService.ValidateAsync(contract.Account, contract.Password);
      if (account == null)
      {
          auditContext.AddDetail("Reason", "帳號或密碼錯誤");
          return Unauthorized();
      }
  
      auditContext.Account = account.Name; // 覆寫操作者帳號
      return Ok();
  }
  
  [HttpPut("{id}")]
  [Audit(AuditAction.Update, "會員")]
  public async Task<IActionResult> UpdateMember(int id, MemberUpdateContract contract, [FromServices] IAuditContext auditContext)
  {
      auditContext.AddDetail("MemberId", id);
      auditContext.AddDetail("ChangedFields", new { contract.Email, contract.Phone });
      // ...
      return Ok();
  }