මාතෘකාව 3: Spring Boot මූලික සිද්ධාන්ත - ඔබගේ පළමු REST API

ශක්තිමත් Java අත්තිවාරමක් සමඟ, දැන් Spring Boot හි බලය මුදා හැරීමට කාලයයි. අපි අපගේ පළමු වෙබ් සේවාව ගොඩනගමු!

3.1 සහ 3.2: ව්‍යාපෘතියේ ව්‍යුහය (Project Structure) තේරුම් ගැනීම

පළමු මාතෘකාවේදී කළාක් මෙන්, අපි start.spring.io වෙතින් නව ව්‍යාපෘතියක් ආරම්භ කරමු. මෙම මාතෘකාව සඳහා අපට අවශ්‍ය එකම dependency එක වන්නේ Spring Web ය. ඔබ ව්‍යාපෘතිය generate කර, download කර, ඔබගේ IDE එකෙහි විවෘත කළ පසු, ඔබට සම්මත directory සැකැස්මක් පෙනෙනු ඇත. මෙම ව්‍යුහය තේරුම් ගැනීම සංවිධානාත්මකව වැඩ කිරීමට ඉතා වැදගත් වේ.

  • pom.xml: මෙය Maven සඳහා වන "Project Object Model" ගොනුවයි. එය ඔබගේ ව්‍යාපෘතියේ නම, dependencies (Spring Web වැනි), සහ එය build කරන ආකාරය නිර්වචනය කරන, ව්‍යාපෘතියේ වින්‍යාසයේ (configuration) හදවතයි.
  • src/main/java: ඔබගේ යෙදුමේ Java කේතයෙන් 99% ක්ම ජීවත් වන්නේ මෙහිය.
    • මෙහි ඇතුළත, @SpringBootApplication annotation එකෙන් සලකුණු කරන ලද ඔබගේ ප්‍රධාන application class එක ඔබට හමුවනු ඇත. මෙම annotation එක මගින් ඔබගේ සම්පූර්ණ යෙදුම ආරම්භ කරයි.
  • src/main/resources: Java නොවන ගොනු සඳහා වන ෆෝල්ඩරයකි.
    • application.properties: ඔබගේ යෙදුම configure කිරීම සඳහා තීරණාත්මක ගොනුවකි (උදා: server port එක සැකසීම, දත්ත සමුදා සම්බන්ධතා විස්තර).

3.3 Controllers, Services, සහ Repositories

නවීන යෙදුම් ගොඩනගා ඇත්තේ වගකීම් වෙන් කිරීම (Separation of Concerns) නම් මූලධර්මය සාක්ෂාත් කර ගැනීම සඳහා ස්ථර ගෘහ නිර්මාණ ශිල්පයක් (layered architecture) භාවිතා කරමිනි. මෙය කේතය සංවර්ධනය කිරීමට, පරීක්ෂා කිරීමට සහ නඩත්තු කිරීමට පහසු කරවන මූලික සැලසුම් මූලධර්මයකි. සෑම ස්ථරයකටම පැහැදිලි වගකීමක් ඇත.

පාරිභෝගික ඉල්ලීම (Browser/Postman)
↓
Controller Layer (HTTP ඉල්ලීම් හසුරුවයි)
↓
Service Layer (Business Logic ක්‍රියාත්මක කරයි)
↓
Repository Layer (දත්ත සමුදාය වෙත ප්‍රවේශ වේ)
↓
දත්ත සමුදාය (Database)

Controller Layer

උපමාව: ආපනශාලාවේ පිළිගැනීමේ නිලධාරියා. Controller යනු ඕනෑම ඉල්ලීමක් සඳහා වන පළමු සම්බන්ධතා ස්ථානයයි. එහි එකම කාර්යය වන්නේ ඉල්ලීම පිළිගෙන, ඉල්ලන්නේ කුමක්දැයි වටහාගෙන (උදා: "මට මෙනුපත බලන්න අවශ්‍යයි" හෝ "මට ඇණවුමක් කිරීමට අවශ්‍යයි"), එම කාර්යය සුදුසු service එකට පැවරීමයි. එය ආහාර පිසින්නේවත්, පිඟන් සෝදන්නේවත් නැත; එය හුදෙක් ඉල්ලීම් සහ ප්‍රතිචාර ගලනය කළමනාකරණය කරයි.

Service Layer

උපමාව: ප්‍රධාන සූපවේදියා. මූලික කාර්යය, එනම් "business logic," සිදු වන්නේ මෙහිය. සූපවේදියා පිළිගැනීමේ නිලධාරියාගෙන් (Controller) ඇණවුම ලබාගෙන, අමුද්‍රව්‍ය (Repository එකෙන්) එකතු කර, ආහාරය පිළියෙල කිරීමේ සැබෑ කාර්යය ඉටු කරයි.

Repository Layer

උපමාව: ගබඩා කාමරය. Repository හි එකම වගකීම වන්නේ දත්ත කළමනාකරණය කිරීමයි. එය දත්ත සමුදාය සමඟ සෘජුවම අන්තර් ක්‍රියා කරයි. සූපවේදියාට (Service) සෑම අමුද්‍රව්‍යයක්ම ගබඩා කර ඇත්තේ කොතැනදැයි දැන ගැනීමට අවශ්‍ය නැත; ඔහු හුදෙක් ගබඩා කාමරයේ කාර්ය මණ්ඩලයෙන් (Repository) "තක්කාලි ගෙඩි දෙකක්" ඉල්ලයි. Repository එක දත්ත ලබා ගැනීම, සුරැකීම, යාවත්කාලීන කිරීම සහ මකා දැමීමේ පහළ මට්ටමේ විස්තර හසුරුවයි.

3.4 REST APIs – හැඳින්වීමක්

API (Application Programming Interface) යනු මෘදුකාංග දෙකකට එකිනෙකා සමඟ සන්නිවේදනය කිරීමට ඉඩ සලසන ගිවිසුමකි. REST API යනු සම්මත HTTP protocol එක භාවිතා කරන ජනප්‍රිය API වර්ගයකි.

එය ආපනශාලාවකින් ආහාර ඇණවුම් කිරීමක් ලෙස සිතන්න:

  • Resource: ඔබ උනන්දුවක් දක්වන "දෙය". අපගේ ව්‍යාපෘතියේදී, resources වනුයේ Customers, Accounts, සහ Transactions ය.
  • URI (Uniform Resource Identifier): Resource එකක් සඳහා වන සුවිශේෂී ලිපිනය. උදා: /api/accounts/12345.
  • HTTP Verbs (Methods): Resource එක මත ඔබ සිදු කිරීමට බලාපොරොත්තු වන ක්‍රියාව.
    • GET: Resource එකක් ලබා ගැනීමට (මෙනුව බැලීමට).
    • POST: නව Resource එකක් සෑදීමට (නව ඇණවුමක් කිරීමට).
    • PUT: පවතින Resource එකක් යාවත්කාලීන කිරීමට (ඔබේ ඇණවුම වෙනස් කිරීමට).
    • DELETE: Resource එකක් ඉවත් කිරීමට (ඔබේ ඇණවුම අවලංගු කිරීමට).

3.5 ඔබගේ පළමු REST API එක ගොඩනගා Postman සමඟින් පරීක්ෂා කිරීම

අපි න්‍යාය ප්‍රායෝගිකව යොදවමු! අපි අපගේ පළමු Controller එක සාදන්නෙමු, එය සරල "Hello World" endpoint එකක් නිරාවරණය කරනු ඇත.

පියවර 1: Controller එක නිර්මාණය කරන්න

ඔබගේ src/main/java package එක තුළ, HelloWorldController.java නමින් නව Java class එකක් සාදන්න.


import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

// @RestController මගින් Spring වෙත පවසන්නේ මෙම class එක web ඉල්ලීම් හසුරුවන බවයි.
@RestController
public class HelloWorldController {

    // @GetMapping("/hello") මගින් "/hello" URL එකට එන HTTP GET ඉල්ලීම්
    // මෙම method එකට යොමු කරයි.
    @GetMapping("/hello")
    public String sayHello() {
        return "නමස්තේ! ඔබගේ පළමු Spring Boot API එකට සාදරයෙන් පිළිගනිමු!";
    }
}

පියවර 2: යෙදුම (Application) ධාවනය කරන්න

ඔබගේ IDE එකේ ඇති ප්‍රධාන application class එකට (@SpringBootApplication සහිත) ගොස්, එය මත Right-click කර "Run" තෝරන්න. ඔබගේ Spring Boot යෙදුම ආරම්භ වන අතර, console එකේ ඔබට log ප්‍රතිදානයන් රාශියක් පෙනෙනු ඇත. අවසානයට ආසන්නව, Tomcat port 8080 මත ආරම්භ වූ බවට රේඛාවක් ඔබට පෙනෙනු ඇත.

පියවර 3: Postman සමඟින් පරීක්ෂා කරන්න

Postman යනු ඕනෑම API සංවර්ධකයෙකුට අත්‍යවශ්‍ය මෙවලමකි. එය frontend එකක් ගොඩනැගීමකින් තොරව ඔබගේ API වෙත HTTP ඉල්ලීම් යැවීමට සහ ප්‍රතිචාර පරීක්ෂා කිරීමට ඔබට ඉඩ සලසයි. ඔබ තවමත් එසේ කර නොමැති නම්, එය බාගත කර ස්ථාපනය කරන්න.

  1. Postman විවෘත කර නව ඉල්ලීමක් සෑදීමට "+" මත ක්ලික් කරන්න.
  2. HTTP method එක GET ලෙස සකසා ඇති බවට වග බලා ගන්න.
  3. URL තීරුවේ, ටයිප් කරන්න: http://localhost:8080/hello
  4. නිල් පැහැති Send බොත්තම ක්ලික් කරන්න.
බලාපොරොත්තු වන ප්‍රතිඵලය: Postman කවුළුවේ පහළ කොටසේ, "නමස්තේ! ඔබගේ පළමු Spring Boot API එකට සාදරයෙන් පිළිගනිමු!" යන පාඨය සහ 200 OK යන status code එක ඔබට පෙනෙනු ඇත.

සුබ පැතුම්! ඔබ ඔබගේ පළමු REST API endpoint එක සාර්ථකව ගොඩනගා පරීක්ෂා කර ඇත. මෙය අප ගොඩනගන බැංකු යෙදුමේ මූලිකම ගොඩනැගීමේ ඒකකයයි.