dotnet7 template webapi full

การใช้งาน Web API เต็มรูปแบบ

นี่คือเทมเพลตที่หมายถึงการตั้งค่าแอปพลิเคชัน Web API ที่ใช้งานอย่างสมบูรณ์โดยใช้ .NET 7

สารบัญ

• สิ่งที่คาดหวัง
• เทคโนโลยี
• การใช้งาน
• แลกเปลี่ยน DBMS
• บทบาทผู้ใช้
• ผู้ตรวจสอบความถูกต้องของผู้ใช้
• ถอนการติดตั้ง
• ใบอนุญาต

สิ่งที่คาดหวัง

• บันทึกที่ปรับแต่งได้อย่างเต็มที่และอัตโนมัติที่เปลี่ยนไฟล์ในช่วงเวลารายวันเพื่อการอ่าน

  แก้ไขค่าในไฟล์ appsettings.json เพื่อปรับแต่ง

  • เส้นทางที่เรียกว่า
  • การกระทำของผู้ใช้
  • ข้อยกเว้น (พร้อมรหัสยกเว้นที่ไม่ซ้ำกันสำหรับการดีบักที่ง่ายขึ้น)
  • ขั้นตอนการตั้งค่าเซิร์ฟเวอร์

• บริการเวอร์ชัน

• การตรวจสอบความถูกต้องของผู้ใช้

  • การตรวจสอบรหัสผ่านที่ปรับแต่งได้

    แก้ไขค่าในไฟล์ appsettings.json เพื่อปรับแต่ง

  • การตรวจสอบอีเมล

  • การตรวจสอบชื่อผู้ใช้

• การรับรองความถูกต้องของ JWT

  • การสร้างผู้ใช้
  • เข้าสู่ระบบและเซสชัน
  • การเข้ารหัสรหัสผ่าน
  • ทั้งบริการสาธารณะและการรับรองความถูกต้อง

• การอนุญาตตามบทบาท

  • ผู้ดูแลระบบและบัญชีสมาชิก

  • บริการผู้ดูแลระบบเท่านั้น

  • บัญชีผู้ใช้ผู้ดูแลระบบเริ่มต้น

    แก้ไขค่าในไฟล์ appsettings.json เพื่อปรับแต่ง

• พร้อมฐานข้อมูล

  • sqlite ตั้งค่าแล้ว
  • สลับ DBMS ได้อย่างง่ายดาย

⬆กลับไปที่สารบัญ

เทคโนโลยี

• . NET 7
• ASP.NET CORE
• ความขยันขันแข็ง
• กรอบเอนทิตี
• JWT
• คนโง่
• sqlite
• พูดพอดี

⬆กลับไปที่สารบัญ

การใช้งาน

1. โคลนที่เก็บ

2. เปิดเทอร์มินัลลงในโฟลเดอร์ของเทมเพลต

    cd webapi-full

3. ติดตั้งเทมเพลตเพื่อใช้สำหรับการสร้างโครงการ

   • สำหรับ Windows

     dotnet new install .

   • สำหรับ macOS / linux

     dotnet new install ./

   คุณอาจต้องถอนการติดตั้งเวอร์ชันหนึ่งเพื่อติดตั้งรุ่นที่อัปเดต

   เพื่อหลีกเลี่ยงความไม่สะดวกนี้เพียงเพิ่มตัวเลือก --force ในคำสั่งข้างต้น

4. สร้างโครงการ

   dotnet new webapi-full

   อย่าลืมเรียกใช้คำสั่งนี้ลงในไดเรกทอรีที่ว่างเปล่าเนื่องจากจะใช้เป็นโฟลเดอร์ของโครงการ

   ตั้งชื่อไดเรกทอรีตามที่คุณต้องการเนมสเปซของโครงการจะได้รับชื่อนั้น

5. เพิ่มการย้ายข้อมูลและสร้างฐานข้อมูล

   dotnet ef migrations add CreateUser

   และ

   dotnet ef database update

   หากคุณไม่ได้ติดตั้งเฟรมเวิร์กเอนทิตีให้เรียกใช้ต่อไปนี้ก่อน:

   dotnet tool install --global dotnet-ef

6. เรียกใช้โครงการและลองใช้ Swagger

   dotnet watch run

⬆กลับไปที่สารบัญ

แลกเปลี่ยน DBMS

มี 2 ​​ระบบการจัดการฐานข้อมูล ที่ฉันจะรวม

• SQL Server
• PostgreSQL

แน่นอนว่ามีอีกมาก แต่สิ่งเหล่านี้เป็นสิ่งที่ฉันเคยทำงานมากที่สุด

สำหรับ ผู้ให้บริการข้อมูล เพิ่มเติมโปรดไปที่เอกสารสำคัญของ EF CORE

SQL Server

1. ติดตั้งแพ็คเกจ Entity Framework Connector

   dotnet add package Microsoft.EntityFrameworkCore.SqlServer

2. เปลี่ยนสตริงการเชื่อมต่อใน appsettings.json เป็นสิ่งนี้:

   {
     "ConnectionStrings" : {
       "Demo" : " Server=<SERVER_NAME>;Database=<DATABASE_NAME>;Trusted_Connection=true;MultipleActiveResultSets=true;Trust Server Certificate=true "
     },
     ...
   }

3. แก้ไขบริการ ApplicationDbContext ของคุณเพื่อใช้ SQL Server

   สิ่งนี้ทำภายใน program.cs

    builder . Services . AddDbContext < ApplicationDbContext > ( options => 
     options . UseSqlServer ( builder . Configuration . GetConnectionString ( "Demo" ) )
   ) ;

PostgreSQL

1. ติดตั้งแพ็คเกจ Entity Framework Connector

   dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL

2. เปลี่ยนสตริงการเชื่อมต่อใน appsettings.json เป็นสิ่งนี้:

   {
     "ConnectionStrings" : {
       "Demo" : " Host=localhost:5432;Database=<DATABASE>;Username=<USERNAME> "
     },
     ...
   }

3. แก้ไขบริการ ApplicationDbContext ของคุณเพื่อใช้ PostgreSQL

   สิ่งนี้ทำภายใน program.cs

    builder . Services . AddDbContext < ApplicationDbContext > ( options => 
     options . UseNpgsql ( builder . Configuration . GetConnectionString ( "Demo" ) )
   ) ;

4. PostgreSQL ต้องการขั้นตอนพิเศษบางอย่างเพื่อให้โซลูชันนี้ทำงานได้

   1. เปลี่ยนคุณสมบัติ Is_Deleted ของคลาส IndexedObject เนื่องจาก DBMs นี้ไม่รองรับประเภท bit

       [ Required ]
      [ Column ( "Is_Deleted" ) ]
      [ JsonIgnore ]
      public bool IsDeleted { get ; set ; } = false ;

   2. เพิ่มรายการต่อไปนี้ cs หลังจากรหัสขั้นตอนที่ 3

       AppContext . SetSwitch ( "Npgsql.EnableLegacyTimestampBehavior" , true ) ;
      AppContext . SetSwitch ( "Npgsql.DisableDateTimeInfinityConversions" , true ) ;

      นี่เป็นสิ่งจำเป็นสำหรับ Postgre เพื่อสนับสนุนคุณสมบัติ DateTime เรา

⬆กลับไปที่สารบัญ

บทบาทผู้ใช้

ประกาศบทบาท

บทบาทของผู้ใช้ถูกกำหนดไว้ใน 2 สถานที่เพื่อให้แอปทำงาน:

1. Role enum

   enum นี้มีบทบาทที่มีอยู่ของแอพรวมถึงดัชนีของแต่ละบทบาท

   ดัชนีนี้มีความสำคัญต่อฟังก์ชั่นของแอปและทำงานอย่างง่าย ๆ : ยิ่งดัชนีสูงขึ้นเท่านั้น

   enum เริ่มต้นมีค่าต่อไปนี้:

   {
     "User" : 1 ,
     "Admin" : 2
   }

   ขอให้สังเกตว่าผู้ดูแลระบบ HES ดัชนีที่สูงขึ้นทำให้เกิดบทบาทที่เหนือกว่า

2. Inside program.cs เพื่อแปลค่า enum เป็น " นโยบาย " ที่ใช้โดยแอป

    builder . Services . AddAuthorization ( options =>
   {
       options . AddPolicy ( "admin" , policy => policy . Requirements . Add ( new RoleRequirement ( Role . Admin ) ) ) ;
       options . AddPolicy ( "user" , policy => policy . Requirements . Add ( new RoleRequirement ( Role . User ) ) ) ;
   } ) ;

   หลังจากเพิ่มบทบาทให้กับ enum มันเป็นข้อบังคับที่จะเพิ่มที่นี่

บริการที่ผ่านการตรวจสอบแล้ว

ในการตรวจสอบสิทธิ์บริการใด ๆ สำหรับผู้ใช้ให้เพิ่มแอตทริบิวต์ [Authorize] อย่างง่าย

มันเป็นสิ่งสำคัญที่จะมีการประกาศบทบาทเช่นกันสำหรับการอนุญาตให้ทำงาน

 [ Authorize ( Policy = "user" ) ]
[ HttpGet ]
public IActionResult GetLoggedUser ( )
{
    User user = this . userUtils . GetLoggedUser ( this . User ) ;

    Log . Information ( $ "Retrieved user ' { user . UserName } '." ) ;

    return Ok ( user ) ;
}

นี่คือบริการที่ผู้ใช้สามารถใช้งานได้

โปรดจำไว้ว่ามันยังไม่ใช่บริการสาธารณะและคุณต้องเข้าสู่ระบบเพื่อใช้งาน เป็นเพียงแค่ไม่จำเป็นต้องมีบทบาทพิเศษ

บัญชีผู้ดูแลระบบเริ่มต้น

ภายใน appsettings.json มีข้อมูลประจำตัวของผู้ดูแลระบบเริ่มต้นและข้อมูลสำคัญ

แอปพลิเคชันใช้ข้อมูลนี้เพื่อสร้างผู้ใช้โดยอัตโนมัติในการสร้างฐานข้อมูล

ข้อมูลถูกประกาศในรูปแบบของ JSON ต่อไปนี้:

 "DefaultAdmin" : {
  "Email" : " [email protected] " ,
  "UserName" : " admin_user " ,
  "FirstName" : " Admin " ,
  "LastName" : " User " ,
  "Password" : " 123 "
}

ขอแนะนำ ให้คุณเปลี่ยนอีเมลและรหัสผ่านอย่างน้อยก่อนดำเนินการ

⬆กลับไปที่สารบัญ

ผู้ตรวจสอบความถูกต้องของผู้ใช้

ชื่อผู้ใช้

การตรวจสอบชื่อผู้ใช้นั้นง่าย แต่ให้ความเห็น

ชื่อผู้ใช้:

• ต้องไม่รวมอักขระ ช่องว่าง ใด ๆ
• ต้องมีความยาวสูงสุด 40 อักขระ
• ต้องมีความยาวขั้นต่ำ 6 อักขระ
• อนุญาตเฉพาะอักขระที่ไม่ได้เป็นตัวอักษรและประจุเท่านั้น:
  • _
  • -
• ไม่สามารถมีตัวอักษรตัวพิมพ์ใหญ่ใด ๆ

ในการส่งคืนรายการกฎทั้งหมดและทำเครื่องหมายข้อความที่ไม่ถูกต้องข้อความที่จัดรูปแบบจะถูกส่งคืนเป็นแท็ก HTML <ul></ul>

โดยเฉพาะอย่างยิ่งนี่คือตัวอย่างของการตรวจสอบที่ล้มเหลว:

 < ul class =' username-validation ' >
  < li class =' valid ' > Username cannot contain whitespaces. </ li >
  < li class =' invalid ' > Username cannot exceed 40 characters. </ li >
  < li class =' valid ' > Username must be at least 6 characters long. </ li >
  < li class =' valid ' > The only allowed special characters are the following: -, _ </ li >
  < li class =' valid ' > Username must be lowercase. </ li >
</ ul >

ในการแก้ไขการตรวจสอบความถูกต้องนี้คุณจะต้องแก้ไขรหัสเนื่องจากกฎถูกบันทึกไว้ สิ่งนี้เกิดขึ้นเนื่องจากการตรวจสอบชื่อผู้ใช้ตามมาตรฐาน

ในตัวอย่างข้างต้นผู้ตรวจสอบทั้งหมดผ่านยกเว้นสำหรับการบังคับใช้ความยาวสูงสุด 40 อักขระ

อีเมล

การตรวจสอบอีเมลนั้นค่อนข้างตรงไปตรงมา

ที่อยู่ทั้งหมดที่ผู้ใช้มีให้นั้นถูกต้องตราบใดที่พวกเขายึดติดกับรูปแบบ

ฉันไม่เห็นประเด็นในการเปลี่ยนผู้ตรวจสอบนี้ แต่คุณมีอิสระที่จะทำในรหัสของคุณ

ทั้งวิธี ValidateEmail และ ValidateUserName ถูกกำหนดเป็นส่วนหนึ่งของอินเตอร์เฟส IUserUtils

รหัสผ่าน

การตรวจสอบรหัสผ่านเป็นสิ่งที่ซับซ้อนและปรับแต่งได้ง่ายที่สุดดังนั้นกฎของมันจึงถูกกำหนดไว้ในไฟล์ appsettings.json

ในรุ่นของแอพคุณจะพบส่วนนี้ในไฟล์ที่กล่าวถึงก่อนหน้านี้:

 "PasswordValidator" : {
  "AllowedNonAlphanumeric" : " !@#$._- " ,
  "MaxLength" : 16 ,
  "MinLength" : 8 ,
  "RequireDigit" : false ,
  "RequireLowercase" : true ,
  "RequireNonAlphanumeric" : true ,
  "RequireUppercase" : true
},

สิ่งนี้คืออะไร:

• ได้รับอนุญาตที่ไม่ใช่ตัวอักษร

  กฎนี้ตั้งค่าอักขระที่ไม่ได้รับอนุญาตที่ได้รับอนุญาตซึ่งสตริงรหัสผ่านที่ได้รับอนุญาต

  อักขระจะต้องไม่ถูกแยกออกจากกัน เพียงแค่ใส่พวกเขาทั้งหมดในสตริง JSON

  หากต้องการไม่อนุญาตให้ไม่มีตัวแปรใด ๆ ให้ทำให้ค่าเป็นสตริงว่างเปล่า

• ความยาวสูงสุด

  ความยาวสูงสุดทำตามที่ชื่อของมันหมายถึง

  หากคุณตั้งค่าเป็นตัวเลขสตริงรหัสผ่านจะต้องไม่เกินความยาวอักขระจำนวนมาก

  หากต้องการหยุดการบังคับใช้ความยาวสูงสุดสำหรับรหัสผ่านให้ตั้งค่าเป็น 0

• ความยาวนาที

  ใช้งานได้เหมือนคู่ความยาวสูงสุด

  รหัสผ่านไม่สามารถมีอักขระน้อยกว่าหมายเลขที่ตั้งไว้สำหรับฟิลด์นี้

  หากต้องการหยุดการบังคับใช้ความยาวขั้นต่ำสำหรับรหัสผ่านให้ตั้งค่าเป็น 0

• ต้องการหลัก

  นี่คือตัวแปร Boolean

  หากตั้งค่าเป็นจริงผู้ใช้จะต้องใช้อย่างน้อย 1 หลัก ( [0-9] ) สำหรับรหัสผ่านของพวกเขา

  หากต้องการไม่บังคับใช้กฎนี้ให้ตั้งค่าเป็น false

• ต้องการตัวพิมพ์เล็ก

  นี่คือตัวแปร Boolean

  หากตั้งค่าเป็นจริงผู้ใช้จะต้องใช้ตัวอักษรตัวพิมพ์เล็กอย่างน้อย 1 ตัวสำหรับรหัสผ่าน

  หากต้องการไม่บังคับใช้กฎนี้ให้ตั้งค่าเป็น false

• ต้องการที่ไม่ใช่ตัวอักษร

  นี่คือตัวแปร Boolean

  หากตั้งค่าเป็น TRUE ผู้ใช้จะต้องใช้อักขระที่ไม่ได้รับอนุญาตอย่างน้อย 1 ตัวสำหรับรหัสผ่าน

  หากต้องการไม่บังคับใช้กฎนี้ให้ตั้งค่าเป็น false

• ต้องการตัวพิมพ์ใหญ่

  นี่คือตัวแปร Boolean

  หากตั้งค่าเป็นจริงผู้ใช้จะต้องใช้ตัวอักษรตัวพิมพ์ใหญ่อย่างน้อย 1 ตัวสำหรับรหัสผ่าน

  หากต้องการไม่บังคับใช้กฎนี้ให้ตั้งค่าเป็น false

• นอกจากนี้โดยค่าเริ่มต้นรหัสผ่านไม่สามารถมีอักขระช่องว่างใด ๆ ได้

ในการส่งคืนรายการกฎทั้งหมดและทำเครื่องหมายข้อความที่ไม่ถูกต้องข้อความที่จัดรูปแบบจะถูกส่งคืนเป็นแท็ก HTML <ul></ul>

โดยเฉพาะอย่างยิ่งนี่คือตัวอย่างของการตรวจสอบที่ล้มเหลว:

 < ul class =' password-validation ' >
  < li class =' valid ' > Password cannot contain whitespaces. </ li >
  < li class =' invalid ' > The only allowed special characters are the following: !, @, #, $, ., _, - </ li >
  < li class =' valid ' > Password cannot exceed 16 characters. </ li >
  < li class =' invalid ' > Password must be at least 8 characters long. </ li >
  < li class =' valid ' > Password must contain at least one digit. </ li >
  < li class =' valid ' > Password must contain at least one lowercase letter. </ li >
</ ul >

ในตัวอย่างข้างต้นรหัสผ่านเกือบจะถูกต้อง แต่มัน:

• มีตัวละครที่ไม่ได้รับอนุญาตและไม่ได้รับอนุญาตและ
• สั้นเกินไป

ในการแก้ไขการตรวจสอบรหัสผ่านคุณ (อาจ) ต้องทำ 3 สิ่ง:

• แก้ไขกฎภายในไฟล์ appsettings.json

• แก้ไขคลาส PasswordValidator เพื่อให้ตรงกับกฎเหล่านั้น

  หากคุณเพียงแค่เปลี่ยนค่าของกฎที่มีอยู่ก็ไม่จำเป็นต้องใช้

• แก้ไขตรรกะของการตรวจสอบที่ประกาศเป็นส่วนหนึ่งของอินเตอร์เฟส IPasswordUtils ภายในคลาสการใช้งานที่ให้มาหรือโดยการสร้างของคุณเอง

  หากคุณเพียงแค่เปลี่ยนค่าของกฎที่มีอยู่ก็ไม่จำเป็นต้องใช้

⬆กลับไปที่สารบัญ

ถอนการติดตั้ง

ในการถอนการติดตั้งเทมเพลตเพียงทำสิ่งต่อไปนี้:

1. เปิดเทอร์มินัลลงในโฟลเดอร์ของเทมเพลต

    cd webapi-full

2. ถอนการติดตั้งเทมเพลตด้วยการรัน:

   • สำหรับ Windows

     dotnet new uninstall .

   • สำหรับ macOS / linux

     dotnet new uninstall ./

⬆กลับไปที่สารบัญ

ใบอนุญาต

Dotnet-Template-Webapi-full ได้รับอนุญาตภายใต้ใบอนุญาตสาธารณะ GNU ทั่วไป v3.0

⬆กลับไปที่สารบัญ