[{"data":1,"prerenderedAt":1605},["ShallowReactive",2],{"navigation_docs":3,"-advanced-go-package-and-api-design":377,"-advanced-go-package-and-api-design-surround":1600},[4,39,114,144,184,244,293,362],{"title":5,"icon":6,"path":7,"stem":8,"children":9,"page":6},"Getting Started",false,"\u002Fgetting-started","1.getting-started",[10,15,20,25,30,35],{"title":11,"path":12,"stem":13,"icon":14},"Learning Path","\u002Fgetting-started\u002Flearning-path","1.getting-started\u002F1.learning-path","i-lucide-map",{"title":16,"path":17,"stem":18,"icon":19},"Introduction","\u002Fgetting-started\u002Fintroduction","1.getting-started\u002F2.introduction","i-lucide-house",{"title":21,"path":22,"stem":23,"icon":24},"Installation","\u002Fgetting-started\u002Finstallation","1.getting-started\u002F3.installation","i-lucide-download",{"title":26,"path":27,"stem":28,"icon":29},"Your First Program","\u002Fgetting-started\u002Ffirst-program","1.getting-started\u002F4.first-program","i-lucide-play",{"title":31,"path":32,"stem":33,"icon":34},"Modules and Dependencies","\u002Fgetting-started\u002Fmodules-and-dependencies","1.getting-started\u002F5.modules-and-dependencies","i-lucide-package-open",{"title":36,"path":37,"stem":38,"icon":34},"Advanced Modules","\u002Fgetting-started\u002Fadvanced-modules","1.getting-started\u002F6.advanced-modules",{"title":40,"path":41,"stem":42,"children":43,"page":6},"Fundamentals","\u002Ffundamentals","2.fundamentals",[44,49,54,59,64,69,74,79,84,89,94,99,104,109],{"title":45,"path":46,"stem":47,"icon":48},"Program Structure","\u002Ffundamentals\u002Fprogram-structure","2.fundamentals\u002F1.program-structure","i-lucide-workflow",{"title":50,"path":51,"stem":52,"icon":53},"Structs and Methods","\u002Ffundamentals\u002Fstructs-and-methods","2.fundamentals\u002F10.structs-and-methods","i-lucide-box",{"title":55,"path":56,"stem":57,"icon":58},"Interfaces","\u002Ffundamentals\u002Finterfaces","2.fundamentals\u002F11.interfaces","i-lucide-plug",{"title":60,"path":61,"stem":62,"icon":63},"Error Handling","\u002Ffundamentals\u002Ferrors","2.fundamentals\u002F12.errors","i-lucide-triangle-alert",{"title":65,"path":66,"stem":67,"icon":68},"Defined Types and Type Aliases","\u002Ffundamentals\u002Fdefined-types","2.fundamentals\u002F13.defined-types","i-lucide-tags",{"title":70,"path":71,"stem":72,"icon":73},"Generics","\u002Ffundamentals\u002Fgenerics","2.fundamentals\u002F14.generics","i-lucide-blocks",{"title":75,"path":76,"stem":77,"icon":78},"Project Structure","\u002Ffundamentals\u002Fproject-structure","2.fundamentals\u002F2.project-structure","i-lucide-folder-tree",{"title":80,"path":81,"stem":82,"icon":83},"Project Layout","\u002Ffundamentals\u002Fproject-layout","2.fundamentals\u002F3.project-layout","i-lucide-layout",{"title":85,"path":86,"stem":87,"icon":88},"Variables and Data Types","\u002Ffundamentals\u002Fvariables-and-types","2.fundamentals\u002F4.variables-and-types","i-lucide-variable",{"title":90,"path":91,"stem":92,"icon":93},"Functions","\u002Ffundamentals\u002Ffunctions","2.fundamentals\u002F5.functions","i-lucide-braces",{"title":95,"path":96,"stem":97,"icon":98},"Control Statements","\u002Ffundamentals\u002Fcontrol-statements","2.fundamentals\u002F6.control-statements","i-lucide-git-branch",{"title":100,"path":101,"stem":102,"icon":103},"Pointers","\u002Ffundamentals\u002Fpointers","2.fundamentals\u002F7.pointers","i-lucide-mouse-pointer-2",{"title":105,"path":106,"stem":107,"icon":108},"Arrays and Slices","\u002Ffundamentals\u002Farrays-and-slices","2.fundamentals\u002F8.arrays-and-slices","i-lucide-list",{"title":110,"path":111,"stem":112,"icon":113},"Maps","\u002Ffundamentals\u002Fmaps","2.fundamentals\u002F9.maps","i-lucide-table-properties",{"title":115,"path":116,"stem":117,"children":118,"page":6},"Concurrency","\u002Fconcurrency","3.concurrency",[119,124,129,134,139],{"title":120,"path":121,"stem":122,"icon":123},"Concurrency Model","\u002Fconcurrency\u002Fconcurrency-model","3.concurrency\u002F1.concurrency-model","i-lucide-network",{"title":125,"path":126,"stem":127,"icon":128},"Goroutines","\u002Fconcurrency\u002Fgoroutines","3.concurrency\u002F2.goroutines","i-lucide-git-fork",{"title":130,"path":131,"stem":132,"icon":133},"Channels","\u002Fconcurrency\u002Fchannels","3.concurrency\u002F3.channels","i-lucide-arrow-left-right",{"title":135,"path":136,"stem":137,"icon":138},"Select and Cancellation","\u002Fconcurrency\u002Fselect-and-cancellation","3.concurrency\u002F4.select-and-cancellation","i-lucide-circle-stop",{"title":140,"path":141,"stem":142,"icon":143},"Synchronization","\u002Fconcurrency\u002Fsynchronization","3.concurrency\u002F5.synchronization","i-lucide-lock-keyhole",{"title":145,"path":146,"stem":147,"children":148,"page":6},"Standard Library","\u002Fstandard-library","4.standard-library",[149,154,159,164,169,174,179],{"title":150,"path":151,"stem":152,"icon":153},"Standard Library Overview","\u002Fstandard-library\u002Foverview","4.standard-library\u002F1.overview","i-lucide-library",{"title":155,"path":156,"stem":157,"icon":158},"Text and Formatting","\u002Fstandard-library\u002Ftext-and-formatting","4.standard-library\u002F2.text-and-formatting","i-lucide-text",{"title":160,"path":161,"stem":162,"icon":163},"Files and JSON","\u002Fstandard-library\u002Ffiles-and-json","4.standard-library\u002F3.files-and-json","i-lucide-file-json",{"title":165,"path":166,"stem":167,"icon":168},"HTTP Clients and Servers","\u002Fstandard-library\u002Fhttp","4.standard-library\u002F4.http","i-lucide-server",{"title":170,"path":171,"stem":172,"icon":173},"Testing","\u002Fstandard-library\u002Ftesting","4.standard-library\u002F5.testing","i-lucide-flask-conical",{"title":175,"path":176,"stem":177,"icon":178},"Command-Line Tools and Configuration","\u002Fstandard-library\u002Fcommand-line-and-configuration","4.standard-library\u002F6.command-line-and-configuration","i-lucide-terminal-square",{"title":180,"path":181,"stem":182,"icon":183},"Structured Logging","\u002Fstandard-library\u002Fstructured-logging","4.standard-library\u002F7.structured-logging","i-lucide-scroll-text",{"title":185,"path":186,"stem":187,"children":188,"page":6},"Backend Development","\u002Fbackend-development","5.backend-development",[189,194,199,204,209,214,219,224,229,234,239],{"title":190,"path":191,"stem":192,"icon":193},"Backend Roadmap","\u002Fbackend-development\u002Fbackend-roadmap","5.backend-development\u002F1.backend-roadmap","i-lucide-route",{"title":195,"path":196,"stem":197,"icon":198},"Graceful Shutdown","\u002Fbackend-development\u002Fgraceful-shutdown","5.backend-development\u002F10.graceful-shutdown","i-lucide-power",{"title":200,"path":201,"stem":202,"icon":203},"Production Checklist","\u002Fbackend-development\u002Fproduction-checklist","5.backend-development\u002F11.production-checklist","i-lucide-clipboard-check",{"title":205,"path":206,"stem":207,"icon":208},"HTTP API Design","\u002Fbackend-development\u002Fhttp-api-design","5.backend-development\u002F2.http-api-design","i-lucide-waypoints",{"title":210,"path":211,"stem":212,"icon":213},"Middleware","\u002Fbackend-development\u002Fmiddleware","5.backend-development\u002F3.middleware","i-lucide-layers-3",{"title":215,"path":216,"stem":217,"icon":218},"Validation","\u002Fbackend-development\u002Fvalidation","5.backend-development\u002F4.validation","i-lucide-list-checks",{"title":220,"path":221,"stem":222,"icon":223},"Application Wiring","\u002Fbackend-development\u002Fapplication-wiring","5.backend-development\u002F5.application-wiring","i-lucide-cable",{"title":225,"path":226,"stem":227,"icon":228},"Observability","\u002Fbackend-development\u002Fobservability","5.backend-development\u002F6.observability","i-lucide-activity",{"title":230,"path":231,"stem":232,"icon":233},"Database SQL","\u002Fbackend-development\u002Fdatabase-sql","5.backend-development\u002F7.database-sql","i-lucide-database",{"title":235,"path":236,"stem":237,"icon":238},"Transactions","\u002Fbackend-development\u002Ftransactions","5.backend-development\u002F8.transactions","i-lucide-repeat-2",{"title":240,"path":241,"stem":242,"icon":243},"Authentication and Authorization","\u002Fbackend-development\u002Fauthentication","5.backend-development\u002F9.authentication","i-lucide-shield-check",{"title":245,"path":246,"stem":247,"children":248,"page":6},"Advanced Go","\u002Fadvanced-go","6.advanced-go",[249,254,259,264,269,274,278,283,288],{"title":250,"path":251,"stem":252,"icon":253},"Advanced Go Roadmap","\u002Fadvanced-go\u002Fadvanced-roadmap","6.advanced-go\u002F1.advanced-roadmap","i-lucide-brain-circuit",{"title":255,"path":256,"stem":257,"icon":258},"Reflection","\u002Fadvanced-go\u002Freflection","6.advanced-go\u002F2.reflection","i-lucide-scan-search",{"title":260,"path":261,"stem":262,"icon":263},"Memory and Garbage Collection","\u002Fadvanced-go\u002Fmemory-and-garbage-collection","6.advanced-go\u002F3.memory-and-garbage-collection","i-lucide-memory-stick",{"title":265,"path":266,"stem":267,"icon":268},"Benchmarking and Profiling","\u002Fadvanced-go\u002Fbenchmarking-and-profiling","6.advanced-go\u002F4.benchmarking-and-profiling","i-lucide-gauge",{"title":270,"path":271,"stem":272,"icon":273},"Advanced Testing and Fuzzing","\u002Fadvanced-go\u002Fadvanced-testing-and-fuzzing","6.advanced-go\u002F5.advanced-testing-and-fuzzing","i-lucide-microscope",{"title":275,"path":276,"stem":277,"icon":48},"Advanced Concurrency","\u002Fadvanced-go\u002Fadvanced-concurrency","6.advanced-go\u002F6.advanced-concurrency",{"title":279,"path":280,"stem":281,"icon":282},"Unsafe and C Boundaries","\u002Fadvanced-go\u002Funsafe-and-cgo","6.advanced-go\u002F7.unsafe-and-cgo","i-lucide-radiation",{"title":284,"path":285,"stem":286,"icon":287},"Package and API Design","\u002Fadvanced-go\u002Fpackage-and-api-design","6.advanced-go\u002F8.package-and-api-design","i-lucide-boxes",{"title":289,"path":290,"stem":291,"icon":292},"Distributed Reliability","\u002Fadvanced-go\u002Fdistributed-reliability","6.advanced-go\u002F9.distributed-reliability","i-lucide-cloud-cog",{"title":294,"path":295,"stem":296,"children":297,"page":6},"Projects","\u002Fprojects","7.projects",[298,316,332,347],{"title":299,"path":300,"stem":301,"children":302,"icon":305},"CLI Task Manager","\u002Fprojects\u002Fcli-task-manager","7.projects\u002F1.cli-task-manager\u002Findex",[303,306,311],{"title":304,"path":300,"stem":301,"icon":305},"Project — CLI Task Manager","i-lucide-list-todo",{"title":307,"path":308,"stem":309,"icon":310},"CLI — Domain and Storage","\u002Fprojects\u002Fcli-task-manager\u002Fdomain-and-storage","7.projects\u002F1.cli-task-manager\u002F1.domain-and-storage","i-lucide-save",{"title":312,"path":313,"stem":314,"icon":315},"CLI — Commands and Tests","\u002Fprojects\u002Fcli-task-manager\u002Fcommands-and-tests","7.projects\u002F1.cli-task-manager\u002F2.commands-and-tests","i-lucide-terminal",{"title":317,"path":318,"stem":319,"children":320,"icon":323},"Concurrent URL Checker","\u002Fprojects\u002Fconcurrent-url-checker","7.projects\u002F2.concurrent-url-checker\u002Findex",[321,324,328],{"title":322,"path":318,"stem":319,"icon":323},"Project — Concurrent URL Checker","i-lucide-radar",{"title":325,"path":326,"stem":327,"icon":128},"URL Checker — Worker Pipeline","\u002Fprojects\u002Fconcurrent-url-checker\u002Fworker-pipeline","7.projects\u002F2.concurrent-url-checker\u002F1.worker-pipeline",{"title":329,"path":330,"stem":331,"icon":173},"URL Checker — Cancellation and Tests","\u002Fprojects\u002Fconcurrent-url-checker\u002Fcancellation-and-tests","7.projects\u002F2.concurrent-url-checker\u002F2.cancellation-and-tests",{"title":333,"path":334,"stem":335,"children":336},"File-backed API","\u002Fprojects\u002Ffile-backed-api","7.projects\u002F3.file-backed-api\u002Findex",[337,339,343],{"title":338,"path":334,"stem":335},"File-backed notes API",{"title":340,"path":341,"stem":342},"File store and concurrency","\u002Fprojects\u002Ffile-backed-api\u002Ffile-store-and-concurrency","7.projects\u002F3.file-backed-api\u002F1.file-store-and-concurrency",{"title":344,"path":345,"stem":346},"HTTP layer and tests","\u002Fprojects\u002Ffile-backed-api\u002Fhttp-and-tests","7.projects\u002F3.file-backed-api\u002F2.http-and-tests",{"title":348,"path":349,"stem":350,"children":351},"Production REST API","\u002Fprojects\u002Fproduction-rest-api","7.projects\u002F4.production-rest-api\u002Findex",[352,354,358],{"title":353,"path":349,"stem":350},"Production REST API capstone",{"title":355,"path":356,"stem":357},"Persistence and authentication","\u002Fprojects\u002Fproduction-rest-api\u002Fpersistence-and-auth","7.projects\u002F4.production-rest-api\u002F1.persistence-and-auth",{"title":359,"path":360,"stem":361},"Operations and release","\u002Fprojects\u002Fproduction-rest-api\u002Foperations-and-release","7.projects\u002F4.production-rest-api\u002F2.operations-and-release",{"title":363,"path":364,"stem":365,"children":366,"page":6},"Meta","\u002Fmeta","99.meta",[367,372],{"title":368,"path":369,"stem":370,"icon":371},"About","\u002Fmeta\u002Fabout","99.meta\u002F1.about","i-lucide-info",{"title":373,"path":374,"stem":375,"icon":376},"Acknowledgements","\u002Fmeta\u002Facknowledgements","99.meta\u002F2.acknowledgements","i-lucide-heart-handshake",{"id":378,"title":284,"body":379,"description":1592,"extension":1593,"links":1594,"meta":1595,"navigation":1596,"path":285,"seo":1597,"stem":286,"__hash__":1599},"docs\u002F6.advanced-go\u002F8.package-and-api-design.md",{"type":380,"value":381,"toc":1577},"minimark",[382,388,393,397,416,420,423,443,446,450,453,513,535,539,542,590,593,709,712,716,770,777,780,783,787,790,793,958,961,965,972,1027,1049,1053,1062,1093,1100,1103,1107,1110,1130,1133,1137,1143,1150,1153,1157,1199,1203,1206,1530,1534,1551,1567,1570,1573],[383,384],"learning-lesson-meta",{"level":385,"prerequisites":386,"time":387},"Advanced","Defined types, interfaces, generics, errors, modules, and project experience","65–80 minutes",[389,390,392],"h2",{"id":391},"what-you-will-learn","What you will learn",[394,395,396],"p",{},"By the end of this lesson, you will be able to:",[398,399,400,404,407,410,413],"ul",{},[401,402,403],"li",{},"define a package around one coherent responsibility;",[401,405,406],{},"make useful zero values and invariants explicit;",[401,408,409],{},"choose constructors, options, interfaces, and concrete types deliberately;",[401,411,412],{},"design context and error contracts;",[401,414,415],{},"evolve an exported API without surprising callers.",[389,417,419],{"id":418},"a-package-is-a-unit-of-understanding","A package is a unit of understanding",[394,421,422],{},"A good package lets a reader answer:",[398,424,425,428,431,434,437,440],{},[401,426,427],{},"What does it provide?",[401,429,430],{},"What does it own?",[401,432,433],{},"What must the caller provide or release?",[401,435,436],{},"Is it safe for concurrent use?",[401,438,439],{},"How does it fail?",[401,441,442],{},"Which parts are stable public contracts?",[394,444,445],{},"Package boundaries should follow responsibility and change, not arbitrary layer counts.",[389,447,449],{"id":448},"name-from-the-callers-perspective","Name from the caller's perspective",[394,451,452],{},"Package names are short, lowercase, and avoid repetition:",[454,455,460],"pre",{"className":456,"code":457,"language":458,"meta":459,"style":459},"language-go shiki shiki-themes solarized-light material-theme one-dark-pro","lesson.Create(...)       \u002F\u002F clearer\nlesson.NewLesson(...)    \u002F\u002F often repetitive\n","go","",[461,462,463,494],"code",{"__ignoreMap":459},[464,465,468,472,476,480,483,487,490],"span",{"class":466,"line":467},"line",1,[464,469,471],{"class":470},"s45-6","lesson",[464,473,475],{"class":474},"shFME",".",[464,477,479],{"class":478},"sisdC","Create",[464,481,482],{"class":474},"(",[464,484,486],{"class":485},"sN42N","...",[464,488,489],{"class":474},")",[464,491,493],{"class":492},"sJsHy","       \u002F\u002F clearer\n",[464,495,497,499,501,504,506,508,510],{"class":466,"line":496},2,[464,498,471],{"class":470},[464,500,475],{"class":474},[464,502,503],{"class":478},"NewLesson",[464,505,482],{"class":474},[464,507,486],{"class":485},[464,509,489],{"class":474},[464,511,512],{"class":492},"    \u002F\u002F often repetitive\n",[394,514,515,516,519,520,519,523,526,527,530,531,534],{},"Avoid generic buckets such as ",[461,517,518],{},"util",", ",[461,521,522],{},"common",[461,524,525],{},"base",", or ",[461,528,529],{},"helpers",". A function named ",[461,532,533],{},"util.Parse"," gives little clue about its domain or ownership.",[389,536,538],{"id":537},"design-a-useful-zero-value","Design a useful zero value",[394,540,541],{},"When practical, make the zero value ready to use:",[454,543,545],{"className":456,"code":544,"language":458,"meta":459,"style":459},"var buffer bytes.Buffer\nbuffer.WriteString(\"ready\")\n",[461,546,547,565],{"__ignoreMap":459},[464,548,549,553,556,560,562],{"class":466,"line":467},[464,550,552],{"class":551},"sEOdo","var",[464,554,555],{"class":470}," buffer",[464,557,559],{"class":558},"snwKR"," bytes",[464,561,475],{"class":474},[464,563,564],{"class":558},"Buffer\n",[464,566,567,570,572,575,577,581,585,587],{"class":466,"line":496},[464,568,569],{"class":470},"buffer",[464,571,475],{"class":474},[464,573,574],{"class":478},"WriteString",[464,576,482],{"class":474},[464,578,580],{"class":579},"sED5a","\"",[464,582,584],{"class":583},"sVazx","ready",[464,586,580],{"class":579},[464,588,589],{"class":474},")\n",[394,591,592],{},"If a type cannot operate safely without configuration or dependencies, prevent invalid construction with unexported fields and a constructor.",[454,594,596],{"className":456,"code":595,"language":458,"meta":459,"style":459},"type Client struct {\n    baseURL *url.URL\n    http    *http.Client\n}\n\nfunc NewClient(baseURL string, httpClient *http.Client) (*Client, error)\n",[461,597,598,612,628,645,651,658],{"__ignoreMap":459},[464,599,600,603,606,609],{"class":466,"line":467},[464,601,602],{"class":551},"type",[464,604,605],{"class":558}," Client",[464,607,608],{"class":551}," struct",[464,610,611],{"class":474}," {\n",[464,613,614,617,620,623,625],{"class":466,"line":496},[464,615,616],{"class":470},"    baseURL",[464,618,619],{"class":551}," *",[464,621,622],{"class":558},"url",[464,624,475],{"class":474},[464,626,627],{"class":558},"URL\n",[464,629,631,634,637,640,642],{"class":466,"line":630},3,[464,632,633],{"class":470},"    http",[464,635,636],{"class":551},"    *",[464,638,639],{"class":558},"http",[464,641,475],{"class":474},[464,643,644],{"class":558},"Client\n",[464,646,648],{"class":466,"line":647},4,[464,649,650],{"class":474},"}\n",[464,652,654],{"class":466,"line":653},5,[464,655,657],{"emptyLinePlaceholder":656},true,"\n",[464,659,661,664,667,669,673,677,680,683,685,687,689,692,694,697,700,702,704,707],{"class":466,"line":660},6,[464,662,663],{"class":551},"func",[464,665,666],{"class":478}," NewClient",[464,668,482],{"class":474},[464,670,672],{"class":671},"syre3","baseURL",[464,674,676],{"class":675},"sF6sA"," string",[464,678,679],{"class":474},",",[464,681,682],{"class":671}," httpClient",[464,684,619],{"class":551},[464,686,639],{"class":558},[464,688,475],{"class":474},[464,690,691],{"class":558},"Client",[464,693,489],{"class":474},[464,695,696],{"class":474}," (",[464,698,699],{"class":551},"*",[464,701,691],{"class":558},[464,703,679],{"class":474},[464,705,706],{"class":675}," error",[464,708,589],{"class":474},[394,710,711],{},"Document whether the caller or package owns injected resources. A package should not close a shared client it did not create unless the contract explicitly transfers ownership.",[389,713,715],{"id":714},"keep-interfaces-at-the-consumer","Keep interfaces at the consumer",[454,717,719],{"className":456,"code":718,"language":458,"meta":459,"style":459},"type LessonStore interface {\n    Find(context.Context, LessonID) (Lesson, error)\n}\n",[461,720,721,733,766],{"__ignoreMap":459},[464,722,723,725,728,731],{"class":466,"line":467},[464,724,602],{"class":551},[464,726,727],{"class":558}," LessonStore",[464,729,730],{"class":551}," interface",[464,732,611],{"class":474},[464,734,735,738,740,743,745,748,750,753,755,757,760,762,764],{"class":466,"line":496},[464,736,737],{"class":478},"    Find",[464,739,482],{"class":474},[464,741,742],{"class":558},"context",[464,744,475],{"class":474},[464,746,747],{"class":558},"Context",[464,749,679],{"class":474},[464,751,752],{"class":558}," LessonID",[464,754,489],{"class":474},[464,756,696],{"class":474},[464,758,759],{"class":558},"Lesson",[464,761,679],{"class":474},[464,763,706],{"class":675},[464,765,589],{"class":474},[464,767,768],{"class":466,"line":630},[464,769,650],{"class":474},[394,771,772,773,776],{},"The service that needs ",[461,774,775],{},"Find"," declares the narrow interface. The repository implementation can expose a concrete type without predicting every consumer's abstraction.",[394,778,779],{},"Return an interface only when callers benefit from multiple hidden implementations or the abstraction is itself the stable product. Returning a concrete value usually preserves more capability and compatibility.",[394,781,782],{},"This is guidance, not a mechanical rule; design from the actual contract.",[389,784,786],{"id":785},"options-and-configuration","Options and configuration",[394,788,789],{},"For a small fixed set of required values, ordinary parameters or a config struct are clearest.",[394,791,792],{},"Functional options can help when optional behaviours grow and defaults are stable:",[454,794,796],{"className":456,"code":795,"language":458,"meta":459,"style":459},"type Option func(*Client) error\n\nfunc WithTimeout(timeout time.Duration) Option {\n    return func(client *Client) error {\n        if timeout \u003C= 0 {\n            return errors.New(\"timeout must be positive\")\n        }\n        client.timeout = timeout\n        return nil\n    }\n}\n",[461,797,798,819,823,849,872,890,914,920,937,947,953],{"__ignoreMap":459},[464,799,800,802,805,808,810,812,814,816],{"class":466,"line":467},[464,801,602],{"class":551},[464,803,804],{"class":558}," Option",[464,806,807],{"class":551}," func",[464,809,482],{"class":474},[464,811,699],{"class":551},[464,813,691],{"class":558},[464,815,489],{"class":474},[464,817,818],{"class":675}," error\n",[464,820,821],{"class":466,"line":496},[464,822,657],{"emptyLinePlaceholder":656},[464,824,825,827,830,832,835,838,840,843,845,847],{"class":466,"line":630},[464,826,663],{"class":551},[464,828,829],{"class":478}," WithTimeout",[464,831,482],{"class":474},[464,833,834],{"class":671},"timeout",[464,836,837],{"class":558}," time",[464,839,475],{"class":474},[464,841,842],{"class":558},"Duration",[464,844,489],{"class":474},[464,846,804],{"class":558},[464,848,611],{"class":474},[464,850,851,855,857,859,862,864,866,868,870],{"class":466,"line":647},[464,852,854],{"class":853},"s7Bcg","    return",[464,856,807],{"class":551},[464,858,482],{"class":474},[464,860,861],{"class":671},"client",[464,863,619],{"class":551},[464,865,691],{"class":558},[464,867,489],{"class":474},[464,869,706],{"class":675},[464,871,611],{"class":474},[464,873,874,877,880,884,888],{"class":466,"line":653},[464,875,876],{"class":853},"        if",[464,878,879],{"class":470}," timeout",[464,881,883],{"class":882},"sRBoR"," \u003C=",[464,885,887],{"class":886},"sAJzr"," 0",[464,889,611],{"class":474},[464,891,892,895,898,900,903,905,907,910,912],{"class":466,"line":660},[464,893,894],{"class":853},"            return",[464,896,897],{"class":470}," errors",[464,899,475],{"class":474},[464,901,902],{"class":478},"New",[464,904,482],{"class":474},[464,906,580],{"class":579},[464,908,909],{"class":583},"timeout must be positive",[464,911,580],{"class":579},[464,913,589],{"class":474},[464,915,917],{"class":466,"line":916},7,[464,918,919],{"class":474},"        }\n",[464,921,923,926,928,930,934],{"class":466,"line":922},8,[464,924,925],{"class":470},"        client",[464,927,475],{"class":474},[464,929,834],{"class":470},[464,931,933],{"class":932},"su2KV"," =",[464,935,936],{"class":470}," timeout\n",[464,938,940,943],{"class":466,"line":939},9,[464,941,942],{"class":853},"        return",[464,944,946],{"class":945},"sp8Z5"," nil\n",[464,948,950],{"class":466,"line":949},10,[464,951,952],{"class":474},"    }\n",[464,954,956],{"class":466,"line":955},11,[464,957,650],{"class":474},[394,959,960],{},"Options can also hide which settings are required, complicate validation, and make discoverability worse. Do not use them merely as a style preference.",[389,962,964],{"id":963},"context-contracts","Context contracts",[394,966,967,968,971],{},"For request-scoped operations, accept ",[461,969,970],{},"context.Context"," as the first parameter:",[454,973,975],{"className":456,"code":974,"language":458,"meta":459,"style":459},"func (c *Client) Fetch(ctx context.Context, id string) (Item, error)\n",[461,976,977],{"__ignoreMap":459},[464,978,979,981,983,986,988,990,992,995,997,1000,1003,1005,1007,1009,1012,1014,1016,1018,1021,1023,1025],{"class":466,"line":467},[464,980,663],{"class":551},[464,982,696],{"class":474},[464,984,985],{"class":671},"c ",[464,987,699],{"class":551},[464,989,691],{"class":558},[464,991,489],{"class":474},[464,993,994],{"class":478}," Fetch",[464,996,482],{"class":474},[464,998,999],{"class":671},"ctx",[464,1001,1002],{"class":558}," context",[464,1004,475],{"class":474},[464,1006,747],{"class":558},[464,1008,679],{"class":474},[464,1010,1011],{"class":671}," id",[464,1013,676],{"class":675},[464,1015,489],{"class":474},[464,1017,696],{"class":474},[464,1019,1020],{"class":558},"Item",[464,1022,679],{"class":474},[464,1024,706],{"class":675},[464,1026,589],{"class":474},[398,1028,1029,1032,1043,1046],{},[401,1030,1031],{},"Do not store ordinary request contexts in a struct.",[401,1033,1034,1035,1038,1039,1042],{},"Do not accept nil contexts; callers should use ",[461,1036,1037],{},"context.Background()"," or ",[461,1040,1041],{},"context.TODO()"," when no better context exists.",[401,1044,1045],{},"Return promptly when cancellation can be observed, and document operations that cannot be interrupted.",[401,1047,1048],{},"Do not add a context parameter to functions that do not perform request-scoped waiting or propagation merely for consistency.",[389,1050,1052],{"id":1051},"error-contracts","Error contracts",[394,1054,1055,1056,1038,1059,475],{},"Callers should know which errors they can inspect with ",[461,1057,1058],{},"errors.Is",[461,1060,1061],{},"errors.As",[454,1063,1065],{"className":456,"code":1064,"language":458,"meta":459,"style":459},"var ErrNotFound = errors.New(\"not found\")\n",[461,1066,1067],{"__ignoreMap":459},[464,1068,1069,1071,1074,1076,1078,1080,1082,1084,1086,1089,1091],{"class":466,"line":467},[464,1070,552],{"class":551},[464,1072,1073],{"class":470}," ErrNotFound",[464,1075,933],{"class":932},[464,1077,897],{"class":470},[464,1079,475],{"class":474},[464,1081,902],{"class":478},[464,1083,482],{"class":474},[464,1085,580],{"class":579},[464,1087,1088],{"class":583},"not found",[464,1090,580],{"class":579},[464,1092,589],{"class":474},[394,1094,1095,1096,1099],{},"Wrapping with ",[461,1097,1098],{},"%w"," makes the wrapped error part of the observable API. Once callers depend on it, changing the underlying error can break their logic.",[394,1101,1102],{},"Expose only error identity and detail callers need. Keep messages useful to humans and avoid forcing callers to parse them.",[389,1104,1106],{"id":1105},"concurrency-and-ownership-documentation","Concurrency and ownership documentation",[394,1108,1109],{},"State whether:",[398,1111,1112,1115,1118,1121,1124,1127],{},[401,1113,1114],{},"a value may be used concurrently;",[401,1116,1117],{},"methods mutate receiver state;",[401,1119,1120],{},"returned slices or maps share internal storage;",[401,1122,1123],{},"callbacks run synchronously or in new goroutines;",[401,1125,1126],{},"the caller must close or release a result;",[401,1128,1129],{},"a function retains provided buffers after returning.",[394,1131,1132],{},"Silence forces callers to guess.",[389,1134,1136],{"id":1135},"compatibility","Compatibility",[394,1138,1139,1140,1142],{},"Adding an exported struct field can affect unkeyed literals. Adding a method to an exported interface breaks external implementations. Changing a wrapped sentinel affects ",[461,1141,1058],{},". Tightening validation can reject previously accepted input.",[394,1144,1145,1146,1149],{},"Use ",[461,1147,1148],{},"internal"," packages to reduce accidental public surface. Export the minimum needed and add compatibility tests for important APIs.",[394,1151,1152],{},"Major incompatible changes require an explicit versioning and migration plan.",[389,1154,1156],{"id":1155},"common-mistakes","Common mistakes",[398,1158,1159,1166,1175,1181,1187,1193],{},[401,1160,1161,1165],{},[1162,1163,1164],"strong",{},"One package per type:"," navigation grows without meaningful boundaries.",[401,1167,1168,1174],{},[1162,1169,1170,1171,1173],{},"A constructor named ",[461,1172,902],{}," that returns invalid values without error:"," invariants remain unclear.",[401,1176,1177,1180],{},[1162,1178,1179],{},"Exporting fields for test convenience:"," callers become coupled to internal representation.",[401,1182,1183,1186],{},[1162,1184,1185],{},"Large provider-owned interfaces:"," consumers must fake methods they never use.",[401,1188,1189,1192],{},[1162,1190,1191],{},"Functional options for two obvious arguments:"," simple calls become indirect.",[401,1194,1195,1198],{},[1162,1196,1197],{},"Documenting behaviour only in implementation comments:"," callers cannot discover the contract.",[389,1200,1202],{"id":1201},"practice","Practice",[394,1204,1205],{},"Design a package for an HTTP-backed weather client. It needs base URL, credentials, timeout, retries for selected requests, concurrent safety, cancellation, and typed not-found\u002Frate-limit errors. Define the public surface and ownership rules without implementing HTTP details.",[1207,1208,1209],"accordion",{},[1210,1211,1214,1513],"accordion-item",{"icon":1212,"label":1213},"i-lucide-lightbulb","Show one possible public API",[454,1215,1217],{"className":456,"code":1216,"language":458,"meta":459,"style":459},"package weather\n\nvar ErrLocationNotFound = errors.New(\"location not found\")\n\ntype RateLimitError struct {\n    RetryAfter time.Duration\n}\n\nfunc (e *RateLimitError) Error() string { return \"weather API rate limit exceeded\" }\n\ntype Config struct {\n    BaseURL    string\n    APIKey     string\n    Timeout    time.Duration\n    MaxRetries int\n}\n\ntype Client struct {\n    \u002F\u002F unexported immutable configuration and shared HTTP client\n}\n\nfunc NewClient(config Config, httpClient *http.Client) (*Client, error)\nfunc (c *Client) Current(ctx context.Context, location string) (Conditions, error)\n",[461,1218,1219,1227,1231,1257,1261,1272,1284,1288,1292,1333,1337,1348,1357,1366,1379,1388,1393,1398,1409,1415,1420,1425,1465],{"__ignoreMap":459},[464,1220,1221,1224],{"class":466,"line":467},[464,1222,1223],{"class":551},"package",[464,1225,1226],{"class":558}," weather\n",[464,1228,1229],{"class":466,"line":496},[464,1230,657],{"emptyLinePlaceholder":656},[464,1232,1233,1235,1238,1240,1242,1244,1246,1248,1250,1253,1255],{"class":466,"line":630},[464,1234,552],{"class":551},[464,1236,1237],{"class":470}," ErrLocationNotFound",[464,1239,933],{"class":932},[464,1241,897],{"class":470},[464,1243,475],{"class":474},[464,1245,902],{"class":478},[464,1247,482],{"class":474},[464,1249,580],{"class":579},[464,1251,1252],{"class":583},"location not found",[464,1254,580],{"class":579},[464,1256,589],{"class":474},[464,1258,1259],{"class":466,"line":647},[464,1260,657],{"emptyLinePlaceholder":656},[464,1262,1263,1265,1268,1270],{"class":466,"line":653},[464,1264,602],{"class":551},[464,1266,1267],{"class":558}," RateLimitError",[464,1269,608],{"class":551},[464,1271,611],{"class":474},[464,1273,1274,1277,1279,1281],{"class":466,"line":660},[464,1275,1276],{"class":470},"    RetryAfter",[464,1278,837],{"class":558},[464,1280,475],{"class":474},[464,1282,1283],{"class":558},"Duration\n",[464,1285,1286],{"class":466,"line":916},[464,1287,650],{"class":474},[464,1289,1290],{"class":466,"line":922},[464,1291,657],{"emptyLinePlaceholder":656},[464,1293,1294,1296,1298,1301,1303,1306,1308,1311,1314,1316,1319,1322,1325,1328,1330],{"class":466,"line":939},[464,1295,663],{"class":551},[464,1297,696],{"class":474},[464,1299,1300],{"class":671},"e ",[464,1302,699],{"class":551},[464,1304,1305],{"class":558},"RateLimitError",[464,1307,489],{"class":474},[464,1309,1310],{"class":478}," Error",[464,1312,1313],{"class":474},"()",[464,1315,676],{"class":675},[464,1317,1318],{"class":474}," {",[464,1320,1321],{"class":853}," return",[464,1323,1324],{"class":579}," \"",[464,1326,1327],{"class":583},"weather API rate limit exceeded",[464,1329,580],{"class":579},[464,1331,1332],{"class":474}," }\n",[464,1334,1335],{"class":466,"line":949},[464,1336,657],{"emptyLinePlaceholder":656},[464,1338,1339,1341,1344,1346],{"class":466,"line":955},[464,1340,602],{"class":551},[464,1342,1343],{"class":558}," Config",[464,1345,608],{"class":551},[464,1347,611],{"class":474},[464,1349,1351,1354],{"class":466,"line":1350},12,[464,1352,1353],{"class":470},"    BaseURL",[464,1355,1356],{"class":675},"    string\n",[464,1358,1360,1363],{"class":466,"line":1359},13,[464,1361,1362],{"class":470},"    APIKey",[464,1364,1365],{"class":675},"     string\n",[464,1367,1369,1372,1375,1377],{"class":466,"line":1368},14,[464,1370,1371],{"class":470},"    Timeout",[464,1373,1374],{"class":558},"    time",[464,1376,475],{"class":474},[464,1378,1283],{"class":558},[464,1380,1382,1385],{"class":466,"line":1381},15,[464,1383,1384],{"class":470},"    MaxRetries",[464,1386,1387],{"class":675}," int\n",[464,1389,1391],{"class":466,"line":1390},16,[464,1392,650],{"class":474},[464,1394,1396],{"class":466,"line":1395},17,[464,1397,657],{"emptyLinePlaceholder":656},[464,1399,1401,1403,1405,1407],{"class":466,"line":1400},18,[464,1402,602],{"class":551},[464,1404,605],{"class":558},[464,1406,608],{"class":551},[464,1408,611],{"class":474},[464,1410,1412],{"class":466,"line":1411},19,[464,1413,1414],{"class":492},"    \u002F\u002F unexported immutable configuration and shared HTTP client\n",[464,1416,1418],{"class":466,"line":1417},20,[464,1419,650],{"class":474},[464,1421,1423],{"class":466,"line":1422},21,[464,1424,657],{"emptyLinePlaceholder":656},[464,1426,1428,1430,1432,1434,1437,1439,1441,1443,1445,1447,1449,1451,1453,1455,1457,1459,1461,1463],{"class":466,"line":1427},22,[464,1429,663],{"class":551},[464,1431,666],{"class":478},[464,1433,482],{"class":474},[464,1435,1436],{"class":671},"config",[464,1438,1343],{"class":558},[464,1440,679],{"class":474},[464,1442,682],{"class":671},[464,1444,619],{"class":551},[464,1446,639],{"class":558},[464,1448,475],{"class":474},[464,1450,691],{"class":558},[464,1452,489],{"class":474},[464,1454,696],{"class":474},[464,1456,699],{"class":551},[464,1458,691],{"class":558},[464,1460,679],{"class":474},[464,1462,706],{"class":675},[464,1464,589],{"class":474},[464,1466,1468,1470,1472,1474,1476,1478,1480,1483,1485,1487,1489,1491,1493,1495,1498,1500,1502,1504,1507,1509,1511],{"class":466,"line":1467},23,[464,1469,663],{"class":551},[464,1471,696],{"class":474},[464,1473,985],{"class":671},[464,1475,699],{"class":551},[464,1477,691],{"class":558},[464,1479,489],{"class":474},[464,1481,1482],{"class":478}," Current",[464,1484,482],{"class":474},[464,1486,999],{"class":671},[464,1488,1002],{"class":558},[464,1490,475],{"class":474},[464,1492,747],{"class":558},[464,1494,679],{"class":474},[464,1496,1497],{"class":671}," location",[464,1499,676],{"class":675},[464,1501,489],{"class":474},[464,1503,696],{"class":474},[464,1505,1506],{"class":558},"Conditions",[464,1508,679],{"class":474},[464,1510,706],{"class":675},[464,1512,589],{"class":474},[394,1514,1515,1516,1518,1519,1522,1523,1038,1526,1529],{},"Document that ",[461,1517,691],{}," is safe for concurrent use, does not close the injected ",[461,1520,1521],{},"http.Client",", validates config without including the API key in errors, retries only documented safe failures with bounded context-aware backoff, and returns ",[461,1524,1525],{},"ErrLocationNotFound",[461,1527,1528],{},"*RateLimitError"," for stable caller decisions.",[389,1531,1533],{"id":1532},"summary","Summary",[398,1535,1536,1539,1542,1545,1548],{},[401,1537,1538],{},"Build packages around one coherent responsibility and ownership model.",[401,1540,1541],{},"Make the zero value useful or prevent invalid construction.",[401,1543,1544],{},"Declare narrow interfaces where behaviour is consumed.",[401,1546,1547],{},"Treat contexts, errors, resource ownership, and concurrency as public API.",[401,1549,1550],{},"Minimise exported surface so future evolution remains possible.",[394,1552,1553,1554,1561,1562,475],{},"Official references: ",[1555,1556,1560],"a",{"href":1557,"rel":1558},"https:\u002F\u002Fgo.dev\u002Fdoc\u002Feffective_go",[1559],"nofollow","Effective Go"," and ",[1555,1563,1566],{"href":1564,"rel":1565},"https:\u002F\u002Fgo.dev\u002Fwiki\u002FCodeReviewComments",[1559],"Go Code Review Comments",[1568,1569],"learning-lesson-complete",{},[1571,1572],"learning-lesson-navigation",{"next":290,"next-label":289,"previous":280,"previous-label":279},[1574,1575,1576],"style",{},"html pre.shiki code .s45-6, html code.shiki .s45-6{--shiki-light:#268BD2;--shiki-default:#EEFFFF;--shiki-dark:#E06C75}html pre.shiki code .shFME, html code.shiki .shFME{--shiki-light:#657B83;--shiki-default:#89DDFF;--shiki-dark:#ABB2BF}html pre.shiki code .sisdC, html code.shiki .sisdC{--shiki-light:#268BD2;--shiki-default:#82AAFF;--shiki-dark:#61AFEF}html pre.shiki code .sN42N, html code.shiki .sN42N{--shiki-light:#859900;--shiki-default:#89DDFF;--shiki-dark:#ABB2BF}html pre.shiki code .sJsHy, html code.shiki .sJsHy{--shiki-light:#93A1A1;--shiki-light-font-style:italic;--shiki-default:#546E7A;--shiki-default-font-style:italic;--shiki-dark:#7F848E;--shiki-dark-font-style:italic}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sEOdo, html code.shiki .sEOdo{--shiki-light:#859900;--shiki-default:#89DDFF;--shiki-dark:#C678DD}html pre.shiki code .snwKR, html code.shiki .snwKR{--shiki-light:#CB4B16;--shiki-default:#FFCB6B;--shiki-dark:#E5C07B}html pre.shiki code .sED5a, html code.shiki .sED5a{--shiki-light:#2AA198;--shiki-default:#89DDFF;--shiki-dark:#98C379}html pre.shiki code .sVazx, html code.shiki .sVazx{--shiki-light:#2AA198;--shiki-default:#C3E88D;--shiki-dark:#98C379}html pre.shiki code .syre3, html code.shiki .syre3{--shiki-light:#657B83;--shiki-light-font-style:inherit;--shiki-default:#EEFFFF;--shiki-default-font-style:italic;--shiki-dark:#E06C75;--shiki-dark-font-style:italic}html pre.shiki code .sF6sA, html code.shiki .sF6sA{--shiki-light:#586E75;--shiki-light-font-weight:bold;--shiki-default:#C792EA;--shiki-default-font-weight:inherit;--shiki-dark:#C678DD;--shiki-dark-font-weight:inherit}html pre.shiki code .s7Bcg, html code.shiki .s7Bcg{--shiki-light:#859900;--shiki-light-font-style:inherit;--shiki-default:#89DDFF;--shiki-default-font-style:italic;--shiki-dark:#C678DD;--shiki-dark-font-style:inherit}html pre.shiki code .sRBoR, html code.shiki .sRBoR{--shiki-light:#859900;--shiki-default:#89DDFF;--shiki-dark:#56B6C2}html pre.shiki code .sAJzr, html code.shiki .sAJzr{--shiki-light:#D33682;--shiki-default:#F78C6C;--shiki-dark:#D19A66}html pre.shiki code .su2KV, html code.shiki .su2KV{--shiki-light:#859900;--shiki-default:#89DDFF;--shiki-dark:#E5C07B}html pre.shiki code .sp8Z5, html code.shiki .sp8Z5{--shiki-light:#B58900;--shiki-default:#89DDFF;--shiki-dark:#D19A66}",{"title":459,"searchDepth":496,"depth":496,"links":1578},[1579,1580,1581,1582,1583,1584,1585,1586,1587,1588,1589,1590,1591],{"id":391,"depth":496,"text":392},{"id":418,"depth":496,"text":419},{"id":448,"depth":496,"text":449},{"id":537,"depth":496,"text":538},{"id":714,"depth":496,"text":715},{"id":785,"depth":496,"text":786},{"id":963,"depth":496,"text":964},{"id":1051,"depth":496,"text":1052},{"id":1105,"depth":496,"text":1106},{"id":1135,"depth":496,"text":1136},{"id":1155,"depth":496,"text":1156},{"id":1201,"depth":496,"text":1202},{"id":1532,"depth":496,"text":1533},"Build small, stable packages that are easy to understand, test, evolve, and use correctly.","md",null,{},{"icon":287},{"description":1598,"title":284},"Learn advanced Go package and API design including naming, zero values, constructors, interfaces, options, contexts, errors, compatibility, and internal packages.","c-yLgXOFgTOnmQ0veYH-x5REo-GpHUr2YgJGfNS2T_E",[1601,1603],{"title":279,"path":280,"stem":281,"description":1602,"icon":282,"children":-1},"Understand what guarantees are lost when using unsafe or cgo and how to isolate the risk.",{"title":289,"path":290,"stem":291,"description":1604,"icon":292,"children":-1},"Design timeouts, retries, idempotency, overload control, and consistency for systems that partially fail.",1794118104031]