गो प्रोजेक्ट संरचना: प्रैक्टिसेज़ और पैटर्न्स

गो प्रोजेक्ट को संरचित करना (https://www.glukhov.org/hi/post/2025/12/go-project-structure/ “गो प्रोजेक्ट को संरचित करना”) लंबे समय तक बनाए रखने, टीम सहयोग, और स्केलेबिलिटी के लिए मौलिक है। फ्रेमवर्क्स की तरह जो कठोर डायरेक्टरी लेआउट्स को लागू करते हैं, गो फ्लेक्सिबिलिटी को अपनाता है—but उस स्वतंत्रता के साथ जिम्मेदारी आती है कि पैटर्न्स चुनें जो आपकी प्रोजेक्ट की विशेष आवश्यकताओं को पूरा करें।

गो के प्रोजेक्ट संरचना पर दर्शन को समझना

गो का मिनिमलिस्ट डिजाइन दर्शन प्रोजेक्ट संगठन तक फैला हुआ है। भाषा को कोई विशेष संरचना निर्धारित नहीं करती, बल्कि डेवलपर्स को सूचित निर्णय लेने का भरोसा करती है। इस दृष्टिकोण ने समुदाय को कई सिद्ध पैटर्न विकसित करने के लिए प्रेरित किया है, छोटी प्रोजेक्ट्स के लिए सरल फ्लैट लेआउट्स से लेकर एंटरप्राइज सिस्टम के लिए जटिल आर्किटेक्चर तक।

मूल सिद्धांत है सादगी पहले, जटिलता जब आवश्यक हो। कई डेवलपर्स अपनी प्रारंभिक संरचना को ओवर-इंजीनियर करने के फंदे में फंस जाते हैं, गहरे नेटेड डायरेक्टरीज और प्रीमैच्योर एब्स्ट्रैक्शन्स बनाते हैं। आज की आवश्यकताओं के साथ शुरू करें, और प्रोजेक्ट बढ़ने के साथ रीफैक्टर करें।

मुझे internal/ डायरेक्टरी का उपयोग कब करना चाहिए और कब pkg/ का?

internal/ डायरेक्टरी गो के डिजाइन में एक विशेष उद्देश्य निभाती है: यह उन पैकेज्स को समाहित करती है जिन्हें बाहरी प्रोजेक्ट्स द्वारा इंपोर्ट नहीं किया जा सकता। गो के कंपाइलर इस प्रतिबंध को लागू करते हैं, जिससे internal/ बाहरी प्रोजेक्ट्स के लिए पुन: उपयोग नहीं होने वाले प्राइवेट एप्लिकेशन लॉजिक, बिजनेस रूल्स, और यूटिलिटीज के लिए आदर्श बन जाता है।

दूसरी ओर, pkg/ डायरेक्टरी यह संकेत देती है कि कोड बाहरी उपयोग के लिए बनाया गया है। केवल तब ही कोड यहां रखें जब आप एक लाइब्रेरी या पुन: उपयोग योग्य घटकों का निर्माण कर रहे हों जिन्हें आप चाहते हैं कि अन्य लोग इंपोर्ट करें। कई प्रोजेक्ट्स को pkg/ की आवश्यकता ही नहीं होती—अगर आपका कोड बाहरी रूप से उपयोग नहीं किया जा रहा है, तो इसे रूट या internal/ में रखना साफ़ है। पुन: उपयोग योग्य लाइब्रेरीज बनाते समय, गो जेनेरिक्स का उपयोग करके टाइप-सेफ, रीयूज़ेबल घटकों का निर्माण करने का विचार करें।

स्टैंडर्ड गो प्रोजेक्ट लेआउट

सबसे व्यापक रूप से मान्यता प्राप्त पैटर्न golang-standards/project-layout है, हालांकि यह महत्वपूर्ण है कि यह एक आधिकारिक मानक नहीं है। एक टाइपिकल संरचना इस तरह दिखती है:

myproject/
├── cmd/
│   ├── api/
│   │   └── main.go
│   └── worker/
│       └── main.go
├── internal/
│   ├── auth/
│   ├── storage/
│   └── transport/
├── pkg/
│   ├── logger/
│   └── crypto/
├── api/
│   └── openapi.yaml
├── config/
│   └── config.yaml
├── scripts/
│   └── deploy.sh
├── go.mod
├── go.sum
└── README.md

cmd/ डायरेक्टरी

cmd/ डायरेक्टरी में आपकी एप्लिकेशन एंट्री पॉइंट्स होती हैं। प्रत्येक सबडायरेक्टरी एक अलग एक्सीक्यूटेबल बाइनरी का प्रतिनिधित्व करती है। उदाहरण के लिए, cmd/api/main.go आपका API सर्वर बनाता है, जबकि cmd/worker/main.go एक बैकग्राउंड जॉब प्रोसेसर बनाता हो सकता है।

बेस्ट प्रैक्टिस: अपने main.go फाइलों को मिनिमल रखें—बस इतना ही कि डिपेंडेंसीज को वायर अप करें, कॉन्फ़िगरेशन लोड करें, और एप्लिकेशन स्टार्ट करें। सभी महत्वपूर्ण लॉजिक को उन पैकेज्स में रखें जिन्हें main.go इंपोर्ट करता है।

// cmd/api/main.go
package main

import (
    "log"
    "myproject/internal/server"
    "myproject/internal/config"
)

func main() {
    cfg, err := config.Load()
    if err != nil {
        log.Fatal(err)
    }

    srv := server.New(cfg)
    if err := srv.Start(); err != nil {
        log.Fatal(err)
    }
}

internal/ डायरेक्टरी

यहाँ आपका प्राइवेट एप्लिकेशन कोड रहता है। गो कंपाइलर किसी भी बाहरी प्रोजेक्ट को internal/ के भीतर पैकेज्स को इंपोर्ट करने से रोकता है, जिससे यह आदर्श बन जाता है:

• बिजनेस लॉजिक और डोमेन मॉडल्स
• एप्लिकेशन सर्विसेज
• इंटरनल एपीआई और इंटरफेस
• डेटाबेस रिपॉजिटरीज (सही ORM चुनने के लिए, हमारी गो ORMs के लिए PostgreSQL तुलना देखें)
• ऑथेंटिकेशन और ऑथोराइजेशन लॉजिक

internal/ को फीचर या डोमेन द्वारा संगठित करें, न कि तकनीकी लेयर द्वारा। internal/handlers/, internal/services/, internal/repositories/ के बजाय, internal/user/, internal/order/, internal/payment/ पसंद करें जहां प्रत्येक पैकेज अपने हैंडलर्स, सर्विसेज, और रिपॉजिटरीज को समाहित करता है।

मुझे एक जटिल डायरेक्टरी संरचना से शुरू करना चाहिए?

कदापि नहीं। अगर आप एक छोटी टूल या प्रोटोटाइप बना रहे हैं, तो इस से शुरू करें:

myproject/
├── main.go
├── go.mod
└── go.sum

जब आपकी प्रोजेक्ट बढ़ती है और आप तार्किक समूहों की पहचान करते हैं, तो डायरेक्टरीज को पेश करें। आप एक db/ पैकेज जोड़ सकते हैं जब डेटाबेस लॉजिक महत्वपूर्ण हो जाता है, या एक api/ पैकेज जब HTTP हैंडलर्स बढ़ जाते हैं। संरचना को स्वाभाविक रूप से उभरने दें बजाय कि इसे आगे से लागू करें।

फ्लैट बनाम नेटेड संरचनाएं: संतुलन खोजना

गो प्रोजेक्ट संरचना में सबसे आम गलतियों में से एक है अतिरिक्त नेटिंग। गो शैलो हायरार्कीज को पसंद करता है—आमतौर पर एक या दो स्तर गहरा। गहरी नेटिंग कोग्निटिव लोड बढ़ाती है और इंपोर्ट्स को असुविधाजनक बनाती है।

सबसे आम गलतियां क्या हैं?

डायरेक्टरीज को ओवर-नेस्ट करना: internal/services/user/handlers/http/v1/ जैसे संरचनाओं से बचें। यह अनावश्यक नेविगेशन जटिलता पैदा करता है। इसके बजाय, internal/user/handler.go का उपयोग करें।

सामान्य पैकेज नाम: utils, helpers, common, या base जैसे नाम कोड स्मेल्स हैं। वे विशिष्ट कार्यक्षमता को व्यक्त नहीं करते और अक्सर असंबंधित कोड के डंपिंग ग्राउंड बन जाते हैं। वर्णनात्मक नामों का उपयोग करें: validator, auth, storage, cache।

चक्रीय निर्भरताएं: जब पैकेज A पैकेज B को इंपोर्ट करता है, और B पैकेज A को इंपोर्ट करता है, तो आपकी एक चक्रीय निर्भरता है—a compilation error in Go। यह आमतौर पर खराब अलगाव का संकेत देता है। इंटरफेस पेश करें या साझा टाइप्स को एक अलग पैकेज में निकालें।

चिंताओं को मिलाना: HTTP हैंडलर्स को HTTP चिंताओं पर केंद्रित रखें, डेटाबेस रिपॉजिटरीज को डेटा एक्सेस पर, और बिजनेस लॉजिक को सर्विस पैकेज्स में। हैंडलर्स में बिजनेस रूल्स रखना परीक्षण को कठिन बनाता है और आपका डोमेन लॉजिक HTTP से जोड़ता है।

डोमेन-ड्रिवन डिजाइन और हेक्सागोनल आर्किटेक्चर

बड़े एप्लिकेशन्स के लिए, विशेष रूप से माइक्रोसर्विसेज, डोमेन-ड्रिवन डिजाइन (DDD) के साथ हेक्सागोनल आर्किटेक्चर स्पष्ट अलगाव प्रदान करता है।

डोमेन-ड्रिवन डिजाइन का पालन करते हुए एक माइक्रोसर्विस को कैसे संरचित करें?

हेक्सागोनल आर्किटेक्चर कोड को केंद्रित परतों में संगठित करता है जहां निर्भरताएं अंदर की ओर बहती हैं:

internal/
├── domain/
│   └── user/
│       ├── entity.go        # डोमेन मॉडल्स और वैल्यू ऑब्जेक्ट्स
│       ├── repository.go    # रिपॉजिटरी इंटरफेस (पोर्ट)
│       └── service.go       # डोमेन सर्विसेज
├── application/
│   └── user/
│       ├── create_user.go   # यूज केस: यूजर बनाना
│       ├── get_user.go      # यूज केस: यूजर प्राप्त करना
│       └── service.go       # एप्लिकेशन सर्विस ऑर्केस्ट्रेशन
├── adapter/
│   ├── http/
│   │   └── user_handler.go  # HTTP एडाप्टर (REST एंडपॉइंट्स)
│   ├── postgres/
│   │   └── user_repo.go     # डेटाबेस एडाप्टर (रिपॉजिटरी पोर्ट को लागू करता है)
│   └── redis/
│       └── cache.go         # कैश एडाप्टर
└── api/
    └── http/
        └── router.go        # रूट कॉन्फ़िगरेशन और मिडलवेयर

डोमेन लेयर (domain/): कोर बिजनेस लॉजिक, एंटिटीज, वैल्यू ऑब्जेक्ट्स, और डोमेन सर्विस इंटरफेस। इस लेयर में बाहरी सिस्टम के लिए कोई निर्भरताएं नहीं हैं—कोई HTTP, कोई डेटाबेस इंपोर्ट्स। यह रिपॉजिटरी इंटरफेस (पोर्ट्स) को परिभाषित करता है जिन्हें एडाप्टर लागू करते हैं।

एप्लिकेशन लेयर (application/): डोमेन ऑब्जेक्ट्स को ऑर्केस्ट्रेट करने वाले यूज केस। प्रत्येक यूज केस (जैसे, “यूजर बनाना”, “पेमेंट प्रोसेस करना”) एक अलग फाइल या पैकेज है। इस लेयर में डोमेन ऑब्जेक्ट्स को समन्वय करता है लेकिन इसमें कोई बिजनेस रूल्स नहीं होते।

एडाप्टर लेयर (adapter/): इनर लेयर्स द्वारा परिभाषित इंटरफेस को लागू करता है। HTTP हैंडलर्स रिक्वेस्ट्स को डोमेन ऑब्जेक्ट्स में बदलते हैं, डेटाबेस रिपॉजिटरीज स्थायित्व लागू करते हैं, मेसेज क्यूज़ एसिंक्रोनस संचार संभालते हैं। इस लेयर में सभी फ्रेमवर्क-स्पेसिफिक और इन्फ्रास्ट्रक्चर कोड होते हैं।

एपीआई लेयर (api/): रूट्स, मिडलवेयर, DTOs (डेटा ट्रांसफर ऑब्जेक्ट्स), एपीआई वर्जनिंग, और ओपनएपीआई स्पेसिफिकेशन्स।

इस संरचना सुनिश्चित करती है कि आपका कोर बिजनेस लॉजिक टेस्टेबल और फ्रेमवर्क्स, डेटाबेस, या बाहरी सर्विसेज से स्वतंत्र बना रहे। आप PostgreSQL को MongoDB के लिए बदल सकते हैं, या REST को gRPC के लिए, बिना डोमेन कोड को छूए।

विभिन्न प्रोजेक्ट प्रकारों के लिए व्यावहारिक पैटर्न

छोटा CLI टूल

कमांड-लाइन एप्लिकेशन्स के लिए, आपको एक संरचना चाहिए जो कई कमांड्स और सबकमांड्स को सपोर्ट करती हो। फ्रेमवर्क्स जैसे कोबरा को कमांड संरचना के लिए और वाइपर को कॉन्फ़िगरेशन मैनेजमेंट के लिए उपयोग करने का विचार करें। हमारा गाइड गो में कोबरा और वाइपर के साथ CLI एप्लिकेशन्स बनाना इस पैटर्न को विस्तार से कवर करता है।

mytool/
├── main.go
├── command/
│   ├── root.go
│   └── version.go
├── go.mod
└── README.md

REST API सर्विस

गो में REST APIs बनाते समय, यह संरचना चिंताओं को साफ़ तरीके से अलग करती है: हैंडलर्स HTTP चिंताओं को हैंडल करते हैं, सर्विसेस बिज़नेस लॉजिक को रखती हैं, और रिपॉज़िटरीज़ डेटा एक्सेस को मैनेज करती हैं। एक व्यापक गाइड के लिए, जो स्टैंडर्ड लाइब्रेरी एप्रोचेस, फ्रेमवर्क्स, ऑथेंटिकेशन, टेस्टिंग पैटर्न्स, और प्रोडक्शन-रेडी बेस्ट प्रैक्टिसेस को कवर करता है, देखें हमारा गो में REST APIs बनाने का पूर्ण गाइड।

myapi/
├── cmd/
│   └── api/
│       └── main.go
├── internal/
│   ├── config/
│   ├── middleware/
│   ├── user/
│   │   ├── handler.go
│   │   ├── service.go
│   │   └── repository.go
│   └── product/
│       ├── handler.go
│       ├── service.go
│       └── repository.go
├── pkg/
│   └── httputil/
├── go.mod
└── README.md

मोनोरिपो के साथ कई सर्विसेस

myproject/
├── cmd/
│   ├── api/
│   ├── worker/
│   └── scheduler/
├── internal/
│   ├── shared/        # शेयर्ड इन्टर्नल पैकेज्स
│   ├── api/          # API-स्पेसिफिक कोड
│   ├── worker/       # वर्कर-स्पेसिफिक कोड
│   └── scheduler/    # स्केड्यूलर-स्पेसिफिक कोड
├── pkg/              # शेयर्ड लाइब्रेरीज़
├── go.work           # गो वर्कस्पेस फाइल
└── README.md

टेस्टिंग और डॉक्युमेंटेशन

टेस्ट फाइल्स को उन कोड के साथ रखें जिन्हें वे टेस्ट करते हैं, _test.go सफ़िक्स का उपयोग करते हुए:

internal/
└── user/
    ├── service.go
    ├── service_test.go
    ├── repository.go
    └── repository_test.go

यह कन्वेंशन टेस्ट्स को इम्प्लीमेंटेशन के करीब रखता है, जिससे उन्हें ढूँढना और मेनटेन करना आसान होता है। कई पैकेज्स को टच करने वाले इंटीग्रेशन टेस्ट्स के लिए, प्रोजेक्ट रूट पर एक अलग test/ डायरेक्टरी बनाएँ। प्रभावी यूनिट टेस्ट्स लिखने के लिए व्यापक गाइड के लिए, जिसमें टेबल-ड्राइवन टेस्ट्स, मॉक्स, कवरेज एनालिसिस, और बेस्ट प्रैक्टिसेस शामिल हैं, देखें हमारा गो यूनिट टेस्टिंग संरचना और बेस्ट प्रैक्टिसेस का गाइड।

डॉक्युमेंटेशन को रखें:

• README.md: प्रोजेक्ट ओवरव्यू, सेटअप इंस्ट्रक्शन्स, बेसिक यूज़ेज
• docs/: विस्तृत डॉक्युमेंटेशन, आर्किटेक्चर डिसीज़न्स, API रेफरेंसेस
• api/: ओपनAPI/स्वैगर स्पेसिफिकेशन्स, प्रोटोबफ डिफ़िनिशन्स

REST APIs के लिए, ओपनAPI डॉक्युमेंटेशन को स्वैगर के साथ जनरेट और सर्व करने की आवश्यकता होती है, जो API डिस्कवरबिलिटी और डेवलपर एक्सपीरियंस के लिए आवश्यक है। हमारा गाइड अपने गो API में स्वैगर जोड़ना पॉपुलर फ्रेमवर्क्स के साथ इंटीग्रेशन और बेस्ट प्रैक्टिसेस को कवर करता है।

गो मॉड्यूल्स के साथ डिपेंडेंसीज़ मैनेज करना

हर गो प्रोजेक्ट को डिपेंडेंसी मैनेजमेंट के लिए गो मॉड्यूल्स का उपयोग करना चाहिए। व्यापक रेफरेंस के लिए गो कमांड्स और मॉड्यूल मैनेजमेंट के लिए, देखें हमारा गो चीटशीट। इनिशियलाइज़ करें:

go mod init github.com/yourusername/myproject

इससे go.mod (डिपेंडेंसीज़ और वर्ज़न्स) और go.sum (वेरिफ़िकेशन के लिए चेकसम्स) बनती हैं। इन फाइल्स को वर्ज़न कंट्रोल में रखें रिप्रोड्यूसिबल बिल्ड्स के लिए।

डिपेंडेंसीज़ को नियमित रूप से अपडेट करें:

go get -u ./...          # सभी डिपेंडेंसीज़ अपडेट करें
go mod tidy              # अनुपयोगी डिपेंडेंसीज़ हटाएँ
go mod verify            # चेकसम्स वेरिफ़ाई करें

मुख्य निष्कर्ष

1. साधारण से शुरू करें, स्वाभाविक रूप से विकसित करें: अपने शुरुआती संरचना को ओवर-इंजीनियर न करें। जब जटिलता मांग करे तब डायरेक्टरीज़ और पैकेज्स जोड़ें।

2. समान स्तरीय हाइरार्कीज़ को प्राथमिकता दें: नेटिंग को एक या दो स्तरों तक सीमित रखें। गो के समान स्तरीय पैकेज संरचना पठनीयता को बढ़ाती है।

3. विवरणात्मक पैकेज नामों का उपयोग करें: सामान्य नामों जैसे utils से बचें। पैकेज्स को उनके कार्य के अनुसार नाम दें: auth, storage, validator।

4. चिंताओं को स्पष्ट रूप से अलग करें: हैंडलर्स को HTTP पर केंद्रित रखें, रिपॉज़िटरीज़ को डेटा एक्सेस पर, और बिज़नेस लॉजिक को सर्विस पैकेज्स में।

5. प्राइवेसी के लिए internal/ का उपयोग करें: इसे उस कोड के लिए उपयोग करें जो बाहरी रूप से इम्पोर्ट नहीं किया जाना चाहिए। अधिकांश एप्लिकेशन कोड यहाँ आता है।

6. जटिल प्रणालियों के लिए आर्किटेक्चर पैटर्न्स लागू करें: हेक्सागोनल आर्किटेक्चर और DDD स्पष्ट सीमाएँ और टेस्टबिलिटी प्रदान करते हैं।

7. गो को आपका मार्गदर्शक बनाएं: गो आइडियम्स का पालन करें अन्य भाषाओं से पैटर्न्स इम्पोर्ट करने के बजाय। गो के पास सरलता और संगठन के बारे में अपना अपना दर्शन है।

उपयोगी लिंक्स

• गो चीटशीट
• गो में REST APIs बनाना: पूर्ण गाइड
• गो में कोबरा और वाइपर के साथ CLI एप्लिकेशन्स बनाना
• गो यूनिट टेस्टिंग: संरचना और बेस्ट प्रैक्टिसेस
• अपने गो API में स्वैगर जोड़ना
• गो जनरिक्स: यूज़ केसेज और पैटर्न्स
• पोस्टग्रेसक्यूएल के लिए गो ORMs की तुलना: GORM vs Ent vs Bun vs sqlc

अन्य संबंधित लेख

• स्टैंडर्ड गो प्रोजेक्ट लेआउट - कम्युनिटी-ड्राइवन प्रोजेक्ट संरचना गाइडलाइन्स
• गो मॉड्यूल्स रेफरेंस - आधिकारिक गो मॉड्यूल्स डॉक्युमेंटेशन
• गो में हेक्सागोनल आर्किटेक्चर - एंटरप्राइज़-ग्रेड हेक्सागोनल आर्किटेक्चर फ्रेमवर्क
• गो में डोमेन-ड्रिवन डिज़ाइन - प्रोडक्शन-रेडी DDD इम्प्लीमेंटेशन
• गो प्रोजेक्ट संरचना कन्वेंशन्स - अतिरिक्त पैटर्न्स और उदाहरण
• एफेक्टिव गो - आधिकारिक गो बेस्ट प्रैक्टिसेस गाइड