Does Goa create client code as well as CLI code?

[RichardJECooke]

Does Goa create client code as well as CLI code?

[raphael]

The idea is that calc.go implements the service package which lives at the root. The service can be instantiated by the command line but that's not the only option. For example there could be multiple services instantiated in a single executable. This follows the clean architecture pattern where the service implements the business logic, the gen directory contains the transport logic and cmd configures and puts everything together. I've used this same structure at scale (hundreds of services) and it works very well.

[RichardJECooke]

goadesign/goa.design#145

[raphael]

Hello!

Goa does generate both server and client code for all services defined in the design. The CLI generator takes advantage of the generated client package to build a tool on top. The weather example in the clue is probably a good place to look at what implementing a service client looks like, see the forecaster service client for example. In particular the New function which instantiates the client by leveraging the generated client package.

The calc.go in the root folder contains the actual business logic. Goa takes care of generating the transport code (both server and client side) as well as the endpoints layer. The user takes advantage of that code to create the actual servers and business logic.

The goa example command provides an example of a main but it certainly isn't the only way to write a main. The actual implementation will depend on a lot of other factors like other downstream dependencies that need to be instantiated (databases, cloud services etc.), the observability stack and other non-Goa dependencies. The same weather example shows an alternative implementation of a main package. At the end of the day the main package doesn't have to be modified much when the design changes. It only needs to be updated when new services are added or services are removed.

The source code for the website is located at https://github.com/goadesign/goa.design - please feel free to submit a PR with any clarification you think would help newcomers like you. I'd be happy to review and merge any submission!

[RichardJECooke]

Thanks. I will definitely make a pull request to clarify the docs if I manage to understand it myself and get it working.

So in the Getting Started calc example - which file would I use on a client to get started? (Not a CLI command, but an actual file in the /gen or /cmd that calls the server)

[raphael]

The code that needs to make calls to the Goa service would import the generated client, for example: https://github.com/goadesign/clue/blob/main/example/weather/services/front/clients/forecaster/client.go#L11.

It then takes advantage of the generated NewClient function to instantiate a client endpoint "factory" object. The signature of the NewClient function depends on the underlying transport (HTTP or gRPC). For HTTP it takes an encoder and decoder which can be set to the default Goa encoder and decoder. This object exposes one method for each service method that returns an endpoint. The endpoint can then be called and/or wrapped as needed.

[RichardJECooke]

Another confusion about your structure.

• Your starting point is /design.
• Your definitions is /gen.
• Your implementation is /cmd.

All good. Your server implementation is in cmd/calc/main.go. This makes sense, as /cmd holds all the placeholder implementation code, and calc is the API name.

But why then is calc.go sitting in the root folder by itself? It's a placeholder implementation of a service, so surely it belongs next to, or below, the placeholder implementation of the API. In other words, in /cmd/calc/calc.go or /cmd/calc/services/calc.go.

[RichardJECooke]

I've finished writing an article for Speakeasy with Goa that we'll publish soon. If you can see anything wrong with what I've said about Goa, please let me know - https://github.com/ritza-co/speakeasy-docs/blob/goa-guide/web/packages/marketing-site/src/pages/docs/api-frameworks/goa.mdx

I'll try to make a pull request to your docs for anything I think can be clearer soon. I still don't understand why service implementations are kept in the root, bu thank you for trying to explain.

[raphael]

Awesome! looking forward to checking it out however I don't seem to have access to the link above (getting a 404).

[RichardJECooke]

Ah, sorry, they made the repository private. Here's another version - ritza-co/speakeasy-goa-example@b802da7. Load diff will show it.

Otherwise the final article will soon appear under - https://www.speakeasyapi.dev/docs/api-frameworks/goa

[raphael]

Thanks for the link, the article looks awesome! Will have to checkout speakeasy :)