Welcome to Google App Engine for Go. With App Engine, you can build web applications using the Go Programming Language . Your Go application runs on Google's scalable infrastructure and uses large-scale persistent storage and services.
Introduction
App Engine builds and executes Go application code using a safe "sandboxed" environment. Your app receives web requests, performs work, and sends responses by interacting with this environment.
The Go SDK provides an interface similar to the standard Go http package ; writing Go App Engine apps is akin to writing stand-alone Go web servers.
The Go runtime environment uses Go
version 1.2
. The SDK includes the Go compiler and standard library, so it has no additional dependencies. As with the other runtimes, not all the standard library's functionality is available inside the sandbox. For example, attempts to open a socket or write to a file will return an
os.ErrPermission
error.
The SDK includes an automated build service to compile your app, so you'll never need to invoke the compiler yourself. And—as with the Python SDK—your app will be automatically re-built whenever you change the source.
The Go runtime environment for App Engine provides full support for goroutines, but not for parallel execution: goroutines are scheduled onto a single operating system thread. This single-thread restriction may be lifted in future versions. Multiple requests may be handled concurrently by a given instance; that means that if one request is, say, waiting for a datastore API call, another request may be processed by the same instance.
Go apps run inside a secure "sandbox" environment with a reduced set of libraries. For instance, an app cannot write data to the local file system or make arbitrary network connections. Instead, apps use scalable services provided by App Engine to store data and communicate over the Internet.
The App Engine platform provides many services that your code can call.
If you haven't already, see the Go Getting Started Guide for an introduction to developing web applications with Go and Google App Engine.
Selecting the Go runtime
App Engine knows to use the Go runtime environment for your application code when you use the tool named
appcfg.py
from the Go SDK with a configuration file named
app.yaml
. You select the Go runtime environment using the following configuration elements:
runtime: go
api_version: go1
The first element,
runtime
, selects the Go runtime environment.
The second element,
api_version
, selects which version of the Go runtime environment to use. As of this writing, the most recent version of the Go environment is
go1
. The version identifier will be incremented when the App Engine team releases changes to the environment that may not be compatible with existing code. This means you can continue to use the older APIs until you are able to update your app and change the
api_version
setting.
Organizing Go apps
When developing an App Engine app in Go, your code is
partitioned into one or more modules; each module is usually contained in its
own directory, along with an
app.yaml
file for the module:
- project-dir
- module1-dir
app.yaml
src1-1.go
src1-2.go
- module2-dir
app.yaml
src2-1.go
src2-2.go
Go applications are organized into packages that mirror the directory structure
of your source files. When you use an
import
statement in App Engine source code,
the SDK tools interpret the relative paths in the
import
two ways:
-
Relative to the directory that contains the module's
app.yamlfile -
Relative to the
srcsubdirectory of all the directories inGOPATH(this is called a "fully-qualifed" import path)
For example, if
GOPATH
is defined this way:
export GOPATH=/home/fred/go
And the file
src1-1.go
in the project directory example above contains this statement:
import "foo/bar"
The SDK will look for the package "foo/bar" in these locations when you run or deploy module1:
project-dir/module1/foo/bar
/home/fred/go/src/foo/bar
If you include your package sources in
GOPATH
, you must be careful not
to place the source code at or below any directories in your App Engine project
that contain
app.yaml
files. If that happens, a package could be loaded twice,
once for the path relative to a module's directory, and once for the
fully-qualified path. This can cause subtle problems, so the Go SDK scans your
project and your
GOPATH
, detects this case, and reports it as
an error.
For best results, we recommend:
- Create a separate directory in your project for each module.
-
Each module directory should contain the module's
app.yamlfile and one or more.gofiles. - Do not include any subdirectories in a module's directory.
-
Your
.gofiles should import packages using fully-qualified paths; place all package code beneathsrcdirectories that are direct children of the project directory, or not under your project directory at all.
For more information about the structuring of Go modules, see Go Module Configuration .
For an introduction to Go's
GOPATH
and how it relates to App Engine
development, please see
The App Engine SDK and workspaces
.
The sandbox
To allow App Engine to distribute requests for applications across multiple web servers, and to prevent one application from interfering with another, the application runs in a restricted "sandbox" environment. In this environment, the application can execute code, store and query data in the App Engine datastore, use the App Engine mail, URL fetch and users services, and examine the user's web request and prepare the response.
An App Engine application cannot:
-
write to the filesystem. Applications must use the App Engine datastore for storing persistent data. Reading from the filesystem is allowed, and all application files uploaded with the application are available.
-
respond slowly. A web request to an application must be handled within a few seconds. Processes that take a very long time to respond are terminated to avoid overloading the web server.
-
make other kinds of system calls.
The Go runtime restricts the use of standard library packages that would
violate the sandbox policies. Such functions have been replaced by stubs that
return an
os.ErrPermission
error or removed entirely.
The Go SDK and tools
The App Engine Go SDK includes tools for testing your application and uploading application files.
The development server runs your application on your local computer for testing your application. The server simulates the App Engine Datastore, services and sandbox restrictions. The development server can also generate configuration for Datastore indices based on the queries the app performs during testing.
A multipurpose tool called
appcfg.py
handles all command-line interaction with your application running on App Engine. The
appcfg.py
tool can upload your application to App Engine, or just update the datastore index configuration so you can build new indexes before updating the code. It can also download the app's log data, so you can analyze your app's performance using your own tools.
The tools used for locally serving apps (
goapp serve
) and for deploying to App Engine production (
goapp deploy
) are typically invoked from within the Go app's root directory.
Alternatively, the application root directory can be added to these commands or a list of the full or relative paths to the
yaml
file(s) of the app can be specified.
Run
goapp help serve
or
goapp help deploy
for more information about these commands.
The SDK also includes some tools from the Go tool chain:
Godoc extracts and generates documentation for Go programs. Godoc uses the source code of the Go standard library and Go App Engine SDK that is included in the SDK zip file.
Gofmt formats Go programs.