That should be where you are heading, because contracts should be separated from implementation, things should not be tightly coupled, etc. This is good programming practice. How can you be opposed to accepting interfaces instead of implementations, especially in a standard library or the standard tooling for the language?
A concrete example: If I have a NewFoo function that returns a Foo and a FooTaker function that accepts a FooInterface, I can't assume that new features I add in NewFoo are usable from FooTaker. If FooTaker just took a Foo, there would be no problems.
This is, I think, the best rule of thumb for when to use an interface: If you expect consumers of your library to write their own data types that could be used by your library, define an interface they can satisfy. Otherwise just produce and consume a struct you control -- it will be much more flexible and maintainable in the long run.
If you assume there is only ever going to be one implementation of "Foo", then there's nothing to be gained by using an interface over a struct with private fields. If there are other implementations, then you have to update every implementation in sync with the interface every time you add or change a method. That might be very difficult or even nigh impossible if they're in different packages maintained by different people.
My point is to be very careful with how you use interfaces. They're designed to represent abstractions that apply to multiple data types. Looking at the standard library, Reader, Writer, Stringer, http.Handler etc are all pretty useful as interfaces. database/sql/driver has the Driver interface, which is about as complicated as you should allow an interface to become. Notice that nothing in database/sql implements the Driver interface -- it's strictly for polymorphism, to consume external implementations -- and nearly every type in database/sql is a raw struct.
Do you have concerns about interface arguments?
Rationale here: https://medium.com/@cep21/what-accept-interfaces-return-stru....
For example, `io.TeeReader` returns `io.Reader` (the interface). The underlying type that implements the tee functionality is left private because you don't need to be able to see it. It really drives home the point that the return value is "just another io.Reader".
Imagine your documentation says: this functions returns a List of items. You can still returns a CopyOnWriteArrayList. Your only promise is that it will satisfy List, but if you returned the interface, you would remove the ability for the next developer, which has more information than you, to rely on it. Since you cannot know in advance who is going to use the return value, giving the most specific type is the approach that is the most composable. A private function that knows what to do with CopyOnWriteArrayList can rely on it. Other code that works on List can accept the value because it is a List.
If your interface is going to be public, then relying on the documentation might not be enough, and then you are welcome to define facade functions which hide internals.
I don't write in Go so I don't know how the Go community feels about this, but I don't like the idea of a mismatch between documentation and implementation. A non-trivial number of people will only read the documentation when something goes wrong. If the function is defined as returning a CopyOnWriteArrayList they will assume that's the return type. If they bother to read the documentation, the mismatch will be confusing and the more obvious inference will be that the documentation is simply out of date.
>you would remove the ability for the next developer, which has more information than you, to rely on it
Yes, this is exactly what I _want_ to do. If the fact that I produce a specialised type rather than an interface is purely incidental, then I don't _want_ people to rely on it -- I won't be able to change my mind later. "Don't promise what you can't deliver." If it's not incidental, then of course be as precise as you feel is appropriate.
Also I'll concede that this opinion is mostly for library writing, less so for internal usage where the caller is you/your team anyway.
Yeah - build your application as a Caddy plugin, then you can use their routing / ACME handling...
There are a lot of similarities. Hopefully Go developers can bypass some of the pitfalls along the journey.